diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..0b245f1
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,2 @@
+# The same lockfile bytes identify production artifacts on every build host.
+Cargo.lock text eol=lf
diff --git a/.github/workflows/platform-delivery.yml b/.github/workflows/platform-delivery.yml
new file mode 100644
index 0000000..31e79c5
--- /dev/null
+++ b/.github/workflows/platform-delivery.yml
@@ -0,0 +1,78 @@
+name: Release builds
+
+on:
+ workflow_dispatch:
+ workflow_call:
+
+permissions:
+ contents: read
+
+jobs:
+ production:
+ name: ${{ matrix.label }}
+ runs-on: ${{ matrix.runner }}
+ timeout-minutes: 90
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - name: apple
+ label: Apple
+ platform: apple
+ runner: macos-15
+ targets: aarch64-apple-ios,aarch64-apple-ios-sim,x86_64-apple-ios,aarch64-apple-darwin,x86_64-apple-darwin
+ manifest: dist/apple/vcore-delivery.json
+ - name: android
+ label: Android
+ platform: android
+ runner: ubuntu-24.04
+ targets: aarch64-linux-android,x86_64-linux-android
+ manifest: dist/android/vcore-delivery.json
+ - name: windows-x64
+ label: Windows x64
+ platform: windows
+ runner: windows-2025
+ targets: x86_64-pc-windows-msvc
+ manifest: dist/windows/x64/vcore-delivery.json
+ - name: windows-arm64
+ label: Windows ARM64
+ platform: windows
+ runner: windows-11-arm
+ targets: aarch64-pc-windows-msvc
+ manifest: dist/windows/arm64/vcore-delivery.json
+ steps:
+ - uses: actions/checkout@v7
+ - uses: dtolnay/rust-toolchain@stable
+ with:
+ targets: ${{ matrix.targets }}
+ components: rustfmt
+ - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+ with:
+ version: "0.12.15"
+ python-version: "3.13"
+ - name: Platform artifact contracts
+ run: uv run --project scripts --locked python -m unittest discover -s scripts/tests -p test_platform_delivery.py
+ - name: Locked source
+ run: cargo fetch --locked
+ - name: Android toolchain
+ if: matrix.platform == 'android'
+ shell: bash
+ run: |
+ "$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager" "ndk;28.2.13676358"
+ echo "ANDROID_NDK_HOME=$ANDROID_HOME/ndk/28.2.13676358" >> "$GITHUB_ENV"
+ - name: Build production artifacts and record identity
+ run: uv run --project scripts --locked vcore-scripts build ${{ matrix.platform }} --delivery
+ - name: Independently verify packaged files
+ run: uv run --project scripts --locked vcore-scripts check platform-artifacts --manifest ${{ matrix.manifest }}
+ - name: Native C ABI and Windows snapshot/startup contracts
+ if: matrix.platform != 'android'
+ run: uv run --project scripts --locked vcore-scripts check platform-abi --manifest ${{ matrix.manifest }}
+ - name: Preserve unsigned artifacts and evidence
+ uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+ with:
+ name: vcore-${{ matrix.name }}-${{ github.sha }}
+ path: |
+ dist/${{ matrix.platform }}/
+ target/platform-delivery/abi/**/result.json
+ if-no-files-found: error
+ retention-days: 14
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 4e451c0..0cbc86e 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -9,25 +9,20 @@ permissions:
contents: read
jobs:
- test:
- runs-on: windows-2025
- timeout-minutes: 30
- steps:
- - uses: actions/checkout@v7
- - uses: dtolnay/rust-toolchain@stable
- - uses: ilammy/msvc-dev-cmd@v1
- with:
- arch: x64
- - name: Build default features
- run: cargo build --locked --all-targets
- - name: Debug tests
- run: cargo test --locked --all-features --all-targets
- - name: Release tests
- run: cargo test --locked --release --all-features --all-targets
-
client-contracts:
+ name: ${{ matrix.name }}
runs-on: macos-15
- timeout-minutes: 45
+ timeout-minutes: 90
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - name: Core tests (Debug)
+ profile: debug
+ - name: Core tests (Release)
+ profile: release
+ - name: Quality and features
+ profile: features
steps:
- uses: actions/checkout@v7
- uses: dtolnay/rust-toolchain@stable
@@ -38,6 +33,7 @@ jobs:
version: "0.12.15"
python-version: "3.13"
- name: Formatting, scripts, and dependency contract
+ if: matrix.profile == 'features'
run: |
cargo fmt --all -- --check
uv run --project scripts --locked python -m unittest discover -s scripts/tests
@@ -45,96 +41,20 @@ jobs:
uv run --project scripts --locked ruff format --check scripts
uv run --project scripts --locked vcore-scripts check c-header
uv run --project scripts --locked vcore-scripts check tls-dependencies
- - name: Minimal and individual protocol features
- run: |
- cargo check --locked --no-default-features --lib
- for features in inbound-http inbound-socks5 outbound-anytls outbound-socks5 outbound-shadowsocks outbound-vless inbound-http,inbound-socks5 ffi; do
- cargo check --locked --no-default-features --features "$features" --lib
- done
- - name: Debug and Release runtime tests
- run: |
- cargo test --locked --all-features --all-targets
- cargo test --locked --release --all-features --all-targets
- cargo test --locked --manifest-path crates/vcore-netstack/Cargo.toml --all-targets
- - name: Production and netstack clippy
+ - name: Production, instrumented harness, and netstack clippy
+ if: matrix.profile == 'features'
run: |
+ cargo clippy --locked --features ffi --lib --bins -- -D warnings
cargo clippy --locked --all-features --lib --bins -- -D warnings
- cargo clippy --locked --features ffi --test mihomo_interop -- -D warnings
+ cargo clippy --locked --features ffi,interop-test --test mihomo_interop -- -D warnings
cargo clippy --locked --manifest-path crates/vcore-netstack/Cargo.toml --all-targets -- -D warnings
+ - name: Run ${{ matrix.name }}
+ run: uv run --project scripts --locked vcore-scripts check core --profile ${{ matrix.profile }}
+ - name: Memory-only netstack tests
+ if: matrix.profile == 'features'
+ run: |
+ cargo test --locked --manifest-path crates/vcore-netstack/Cargo.toml --all-targets
platform-build:
- name: Release ${{ matrix.name }}
- runs-on: ${{ matrix.runner }}
- timeout-minutes: 60
- strategy:
- fail-fast: false
- matrix:
- include:
- - name: apple
- platform: apple
- runner: macos-15
- targets: aarch64-apple-ios,aarch64-apple-ios-sim,x86_64-apple-ios,aarch64-apple-darwin,x86_64-apple-darwin
- - name: android
- platform: android
- runner: ubuntu-24.04
- targets: aarch64-linux-android,x86_64-linux-android
- - name: windows-x64
- platform: windows
- runner: windows-2025
- targets: x86_64-pc-windows-msvc
- - name: windows-arm64
- platform: windows
- runner: windows-11-arm
- targets: aarch64-pc-windows-msvc
- steps:
- - uses: actions/checkout@v7
- - uses: dtolnay/rust-toolchain@stable
- with:
- targets: ${{ matrix.targets }}
- components: rustfmt
- - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
- with:
- version: "0.12.15"
- python-version: "3.13"
- - name: Record locked source and toolchain
- run: |
- git rev-parse HEAD
- rustc --version --verbose
- cargo fetch --locked
- - name: Apple SDK versions
- if: matrix.platform == 'apple'
- run: |
- xcodebuild -version
- xcodebuild -showsdks
- - name: Build Android with the pinned NDK
- if: matrix.platform == 'android'
- shell: bash
- run: |
- sdkmanager "ndk;28.2.13676358"
- export ANDROID_NDK_HOME="$ANDROID_HOME/ndk/28.2.13676358"
- "$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/linux-x86_64/bin/clang" --version
- uv run --project scripts --locked vcore-scripts build android
- - name: Build native platform artifacts
- if: matrix.platform != 'android'
- run: uv run --project scripts --locked vcore-scripts build ${{ matrix.platform }}
- - name: Record Unix artifact hashes
- if: runner.os != 'Windows'
- shell: bash
- run: |
- shasum -a 256 Cargo.lock
- find dist -type f -exec shasum -a 256 {} +
- - name: Record Windows artifact hashes
- if: runner.os == 'Windows'
- shell: pwsh
- run: |
- Get-FileHash Cargo.lock -Algorithm SHA256
- Get-ChildItem dist -Recurse -File | Get-FileHash -Algorithm SHA256
- - name: Preserve unsigned build artifacts
- uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
- with:
- name: vcore-${{ matrix.name }}-${{ github.sha }}
- path: |
- dist/${{ matrix.platform }}/
- Cargo.lock
- if-no-files-found: error
- retention-days: 7
+ name: Release builds
+ uses: ./.github/workflows/platform-delivery.yml
diff --git a/AGENTS.md b/AGENTS.md
index 2637745..2bd8ab5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
# Project Overview
-VCore is a standalone Rust proxy core. The current public contract is Invoke API v5 with internal schema revision 14. Runtime configuration uses the strict schema documented in `docs/config.yaml` and is passed inline as `configYaml` / `configYamls`; YAML contains neither `configVersion` nor `default-proxy`. Public lifecycle state is runtime-local and single-instance.
+VCore is a standalone Rust proxy core. The current public contract is Invoke API v5 with internal schema revision 27. Runtime configuration uses the strict schema documented in `docs/config.yaml` and is passed inline as `configYaml` / `configYamls`; YAML contains neither `configVersion` nor `default-proxy`. Public lifecycle state is runtime-local and single-instance.
Apple and Android use host-owned TUN fds through the Unix `rust-tun` adapter. Windows uses `windows-rs` / `Windows.Networking.Vpn`; the packaged ARM64 foreground, AppContainer provider, per-session full-trust runtime, lifecycle, pressure, and packet-channel gates pass on Windows 11. Windows 10, native x64, physical IPv6, WACK, and Store publishing remain release gates. Linux remains unsupported.
@@ -12,15 +12,17 @@ Read the relevant document completely before changing that area:
- FFI, lifecycle, Android protect, or config delivery: `docs/invoke-api.md` and `src/ffi/`.
- YAML, proxy graph, proxy groups, DNS, rules, or sniffer: `docs/config.yaml`, `docs/tun-icmp-dns.md`, and `src/config/`.
-- HTTP/SOCKS5 inbound, authentication, or client listener policy: `docs/http-proxy.md`, `docs/socks5-proxy.md`, and `src/inbound/`.
-- AnyTLS: `docs/anytls.md`.
-- Shadowsocks 2022 and its narrowly scoped AWS-LC dependency exception: `docs/shadowsocks.md`.
+- HTTP/SOCKS5 inbound, authentication, or listeners: `docs/inbounds.md` and `src/inbound/`.
+- SOCKS5, AnyTLS, Trojan, VMess, Hysteria2 or SS 2022: `docs/outbounds.md`.
+- VLESS, Vision, Encryption, JLS or static ECH: `docs/vless.md`.
+- XHTTP request fields, download legs, H1/H2/H3 or sing-mux: `docs/xhttp.md`.
- Runtime Controller, proxy-group selection, or TUN traffic metrics: `docs/controller-api.md` and `src/controller.rs`.
- GeoData: `docs/geodata.md`.
-- REALITY or the GitHub rustls fork: `docs/reality-wire-protocol.md` and `docs/rustls-reality-release.md`.
+- TLS profiles, certificate policy or TLS dependencies: `docs/tls-client-fingerprint.md` and `docs/tls-dependencies.md`; REALITY also requires `docs/reality-wire-protocol.md`.
- Unix TUN fd ownership or packet I/O: `docs/tun-platform.md`.
-- Windows VPN/TUN, outbound binding, AppContainer packet buffers, or package lifecycle: `docs/windows-vpn.md`, `docs/windows-session-runtime.md`, and `docs/tun-platform.md`.
-- Build, validation, or interoperability tooling: `scripts/README.md` and the unified `vcore-scripts` interface.
+- Windows VPN/TUN, outbound binding, AppContainer packet buffers, or package lifecycle: `docs/windows-vpn.md` and `docs/tun-platform.md`.
+- Build, validation, or interoperability tooling: `scripts/README.md`, `tests/README.md`, and the unified `vcore-scripts` interface.
+- Server-side tests: `docs/testing-isolation.md`. All new server peers and network origins must run in isolated containers; never fall back to native host servers.
- Claims that something passed: `docs/acceptance.md`. Record only commands and environments actually executed; host tests and cross-builds do not prove physical-device data paths.
# Architecture Boundaries
@@ -46,6 +48,7 @@ Read the relevant document completely before changing that area:
8. When copying or modifying third-party source, record the upstream project and preserve all applicable license terms. Audit linked dependencies against the resolved release graph. Do not describe independent rewrites, protocol interoperability, or architectural references as derived source without evidence; Credits provide context and attribution, not a substitute for release license review.
9. Keep every public surface—code, documentation, tests, examples, commits, issues, pull requests, reviews, CI output, and releases—limited to VCore and public dependencies. Keep private downstream repository or product identities, links, implementation details, status, artifacts, and roadmaps outside this repository and its GitHub surfaces. Before publishing, search the staged diff and proposed GitHub text for downstream identifiers.
10. Make changes on a separate branch, never directly on `main`.
+11. Use the official latest stable third-party dependencies, including test-only experiments. Check current non-prerelease, non-yanked releases when selecting or upgrading them; reference projects' old pins are not a version policy. Keep lockfiles for reproducible validation, refresh affected dependency audits, and rerun applicable tests. If freshness conflicts with the approved fork/provider or a platform's compatible dependency set, report the conflict and obtain an explicit exception or scope decision instead of silently retaining an old version or changing the security architecture.
# Validation
@@ -53,7 +56,9 @@ Choose the smallest relevant set, then expand for shared contracts:
```shell
cargo fmt --all -- --check
-cargo test --all-features --all-targets
+uv run --project scripts --locked vcore-scripts check core --profile debug
+# All-target compilation only; network peers must be containerized.
+cargo test --locked --all-features --all-targets --no-run
cargo clippy --locked --all-features --lib --bins -- -D warnings
cargo test --manifest-path crates/vcore-netstack/Cargo.toml --all-targets
cargo clippy --manifest-path crates/vcore-netstack/Cargo.toml --all-targets -- -D warnings
@@ -62,8 +67,6 @@ uv run --project scripts --locked vcore-scripts check tls-dependencies
uv run --project scripts --locked python -m unittest discover -s scripts/tests
uv run --project scripts --locked ruff check scripts
uv run --project scripts --locked ruff format --check scripts
-sh -n tests/run_xray_interop.sh tests/run_anytls_interop.sh
-sh -n tests/run_mihomo_interop.sh
git diff --check
```
diff --git a/Cargo.lock b/Cargo.lock
index 844140d..dbd7cb7 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2,13 +2,19 @@
# It is not intended for manual editing.
version = 4
+[[package]]
+name = "adler2"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
+
[[package]]
name = "aead"
version = "0.6.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1973cfbc1a2daf9cf550e74e1f088c28e7f7d8c1e1418fb6c9dc5184b7e84c99"
dependencies = [
- "crypto-common 0.2.2",
+ "crypto-common",
"inout",
]
@@ -20,7 +26,8 @@ checksum = "35f0f96ce78e38c3dc6d8948aa8163d06385be74000f3c7a95bf1eef35d3ea32"
dependencies = [
"cipher",
"cpubits",
- "cpufeatures 0.3.1",
+ "cpufeatures",
+ "zeroize",
]
[[package]]
@@ -37,6 +44,30 @@ dependencies = [
"ghash",
]
+[[package]]
+name = "aho-corasick"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "alloc-no-stdlib"
+version = "3.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2fb6cfd47bf496ff64095c20eaba0c201404ee38714d4142fcfa1dc334fcc7a"
+
+[[package]]
+name = "alloc-stdlib"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b5c1865780388bfa186411ab5f247819487fc4864c6e9c3106611fa347586e1"
+dependencies = [
+ "alloc-no-stdlib",
+]
+
[[package]]
name = "arc-swap"
version = "1.9.2"
@@ -76,8 +107,8 @@ checksum = "3109e49b1e4909e9db6515a30c633684d68cdeaa252f215214cb4fa1a5bfee2c"
dependencies = [
"proc-macro2",
"quote",
- "syn 2.0.118",
- "synstructure",
+ "syn 2.0.119",
+ "synstructure 0.13.2",
]
[[package]]
@@ -88,7 +119,7 @@ checksum = "7b18050c2cd6fe86c3a76584ef5e0baf286d038cda203eb6223df2cc413565f7"
dependencies = [
"proc-macro2",
"quote",
- "syn 2.0.118",
+ "syn 2.0.119",
]
[[package]]
@@ -111,13 +142,13 @@ checksum = "8b75356056920673b02621b35afd0f7dda9306d03c79a30f5c56c44cf256e3de"
[[package]]
name = "async-trait"
-version = "0.1.89"
+version = "0.1.92"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9035ad2d096bed7955a320ee7e2230574d28fd3c3a0f186cbea1ff3c7eed5dbb"
+checksum = "82f6aeea286b8eb4dd3431a1be1b59d290ace00f5bfd8e2a159bc2a05e2c1667"
dependencies = [
"proc-macro2",
"quote",
- "syn 2.0.118",
+ "syn 3.0.6",
]
[[package]]
@@ -156,18 +187,30 @@ dependencies = [
"pkg-config",
]
-[[package]]
-name = "base64"
-version = "0.22.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
-
[[package]]
name = "base64"
version = "0.23.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ac07cdecf99051d9a5238b80f35af32cdeba5b336e55d957b318b50137e18da5"
+[[package]]
+name = "bindgen"
+version = "0.72.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "993776b509cfb49c750f11b8f07a46fa23e0a1386ffc01fb1e7d343efc387895"
+dependencies = [
+ "bitflags 2.13.2",
+ "cexpr",
+ "clang-sys",
+ "itertools",
+ "proc-macro2",
+ "quote",
+ "regex",
+ "rustc-hash",
+ "shlex 1.3.0",
+ "syn 2.0.119",
+]
+
[[package]]
name = "bit-vec"
version = "0.9.1"
@@ -185,9 +228,18 @@ checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"
[[package]]
name = "bitflags"
-version = "2.13.0"
+version = "2.13.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b4388bee8683e3d04af747c73422af53102d2bd24d9eadb6cbc100baef4b43f8"
+checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"
+
+[[package]]
+name = "blake2"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5b5d4d889834ee8ecfc0f8426ad30faf7cdcb10f741a8e6d7224d95325479f6f"
+dependencies = [
+ "digest",
+]
[[package]]
name = "blake3"
@@ -199,16 +251,7 @@ dependencies = [
"cc",
"cfg-if",
"constant_time_eq",
- "cpufeatures 0.3.1",
-]
-
-[[package]]
-name = "block-buffer"
-version = "0.10.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"
-dependencies = [
- "generic-array",
+ "cpufeatures",
]
[[package]]
@@ -222,9 +265,9 @@ dependencies = [
[[package]]
name = "blocking"
-version = "1.6.2"
+version = "1.7.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e83f8d02be6967315521be875afa792a316e28d57b5a2d401897e2a7921b7f21"
+checksum = "a70e4329df6cb94385eed412ec92375c3cdd8a6e502493d1229b6414e4036dfa"
dependencies = [
"async-channel",
"async-task",
@@ -233,6 +276,52 @@ dependencies = [
"piper",
]
+[[package]]
+name = "boring"
+version = "5.2.0"
+source = "git+https://github.com/OneXray/boring?branch=release#d5a5d41850886aef5b269015130ee6d6eb2129ba"
+dependencies = [
+ "bitflags 2.13.2",
+ "boring-sys",
+ "brotli",
+ "flate2",
+ "foreign-types",
+ "libc",
+ "openssl-macros",
+]
+
+[[package]]
+name = "boring-sys"
+version = "5.2.0"
+source = "git+https://github.com/OneXray/boring?branch=release#d5a5d41850886aef5b269015130ee6d6eb2129ba"
+dependencies = [
+ "bindgen",
+ "cmake",
+ "fs_extra",
+ "fslock",
+]
+
+[[package]]
+name = "brotli"
+version = "9.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8b851b75c23ca7873623d612fe49bd1989aeb03d08fb9432187eb253d3d4c6b"
+dependencies = [
+ "alloc-no-stdlib",
+ "alloc-stdlib",
+ "brotli-decompressor",
+]
+
+[[package]]
+name = "brotli-decompressor"
+version = "6.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "941cd9bd4ddab83cb46fa5a2d428f1c857b24ac78cb876cf7beb710840934bd7"
+dependencies = [
+ "alloc-no-stdlib",
+ "alloc-stdlib",
+]
+
[[package]]
name = "bumpalo"
version = "3.20.3"
@@ -259,21 +348,30 @@ checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
[[package]]
name = "cc"
-version = "1.2.67"
+version = "1.5.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e17dd265a7d0f31ef544e1b20e03add05d3b45b491b633b10d67145d2acc1a38"
+checksum = "f360145194ee8e21db5ee7f3fcd4fe52210864c75c985dae33218202c8bbe040"
dependencies = [
"find-msvc-tools",
"jobserver",
"libc",
- "shlex",
+ "shlex 2.0.1",
+]
+
+[[package]]
+name = "cexpr"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6fac387a98bb7c37292057cffc56d62ecb629900026402633ae9160df93a8766"
+dependencies = [
+ "nom",
]
[[package]]
name = "cfg-if"
-version = "1.0.4"
+version = "1.0.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
[[package]]
name = "cfg_aliases"
@@ -289,8 +387,8 @@ checksum = "65c35e4b699c7e15ccbe7ee35c005e4fc0a278d22238a2857e6ce2dadeda1b06"
dependencies = [
"cfg-if",
"cipher",
- "cpufeatures 0.3.1",
- "rand_core 0.10.1",
+ "cpufeatures",
+ "rand_core",
]
[[package]]
@@ -311,11 +409,22 @@ version = "0.5.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e8cf2a2c93cd704877c0858356ed03480ff301ee950b43f1cbe4573b088bfa6c"
dependencies = [
- "block-buffer 0.12.1",
- "crypto-common 0.2.2",
+ "block-buffer",
+ "crypto-common",
"inout",
]
+[[package]]
+name = "clang-sys"
+version = "1.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "157a8ba7b480713b56f4c09fd13fc3e0a22a5dfab8097ba61cbc5feef950788a"
+dependencies = [
+ "glob",
+ "libc",
+ "libloading 0.8.9",
+]
+
[[package]]
name = "cmake"
version = "0.1.58"
@@ -340,6 +449,12 @@ dependencies = [
"crossbeam-utils",
]
+[[package]]
+name = "const-oid"
+version = "0.10.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6ef517f0926dd24a1582492c791b6a4818a4d94e789a334894aa15b0d12f55c"
+
[[package]]
name = "constant_time_eq"
version = "0.4.2"
@@ -352,15 +467,6 @@ version = "0.1.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "15b85f9c39137c3a891689859392b1bd49812121d0d61c9caf00d46ed5ce06ae"
-[[package]]
-name = "cpufeatures"
-version = "0.2.17"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280"
-dependencies = [
- "libc",
-]
-
[[package]]
name = "cpufeatures"
version = "0.3.1"
@@ -371,20 +477,19 @@ dependencies = [
]
[[package]]
-name = "crossbeam-utils"
-version = "0.8.22"
+name = "crc32fast"
+version = "1.5.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "61803da095bee82a81bb1a452ecc25d3b2f1416d1897eb86430c6159ef717c17"
+checksum = "01a7799fd6b852db0e61728dde9a204c423b44d689dbd432522543614b490e78"
+dependencies = [
+ "cfg-if",
+]
[[package]]
-name = "crypto-common"
-version = "0.1.7"
+name = "crossbeam-utils"
+version = "0.8.23"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
-dependencies = [
- "generic-array",
- "typenum",
-]
+checksum = "a31eee39dddec8330830986fcd7625edb5a24ec90ea038215273bbc3adb08ac6"
[[package]]
name = "crypto-common"
@@ -394,7 +499,7 @@ checksum = "ce6e4c961d6cd6c9a86db418387425e8bdeaf05b3c8bc1411e6dca4c252f1453"
dependencies = [
"getrandom 0.4.3",
"hybrid-array",
- "rand_core 0.10.1",
+ "rand_core",
]
[[package]]
@@ -417,12 +522,12 @@ dependencies = [
[[package]]
name = "curve25519-dalek"
-version = "4.1.3"
+version = "5.0.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "97fb8b7c4503de7d6ae7b42ab72a5a59857b4c937ec27a3d4539dba95b5ab2be"
+checksum = "b5eed333089e2e1c1ac8c6c0398e5e2497b4c9926ca6d0365ed1e099afa5bc23"
dependencies = [
"cfg-if",
- "cpufeatures 0.2.17",
+ "cpufeatures",
"curve25519-dalek-derive",
"fiat-crypto",
"rustc_version",
@@ -438,7 +543,7 @@ checksum = "f46882e17999c6cc590af592290432be3bce0428cb0d5f8b6715e4dc7b383eb3"
dependencies = [
"proc-macro2",
"quote",
- "syn 2.0.118",
+ "syn 2.0.119",
]
[[package]]
@@ -447,15 +552,6 @@ version = "2.11.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4583a4551df46e2792f82ceeac45e850d2e2d5debba0b91f102385cda5b11f06"
-[[package]]
-name = "defmt"
-version = "0.3.100"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f0963443817029b2024136fc4dd07a5107eb8f977eaf18fcd1fdeb11306b64ad"
-dependencies = [
- "defmt 1.1.1",
-]
-
[[package]]
name = "defmt"
version = "1.1.1"
@@ -475,7 +571,7 @@ dependencies = [
"defmt-parser",
"proc-macro2",
"quote",
- "syn 2.0.118",
+ "syn 2.0.119",
]
[[package]]
@@ -509,23 +605,25 @@ checksum = "7cd812cc2bc1d69d4764bd80df88b4317eaef9e773c75226407d9bc0876b211c"
[[package]]
name = "digest"
-version = "0.10.7"
+version = "0.11.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
+checksum = "f1dd6dbb5841937940781866fa1281a1ff7bd3bf827091440879f9994983d5c2"
dependencies = [
- "block-buffer 0.10.4",
- "crypto-common 0.1.7",
+ "block-buffer",
+ "const-oid",
+ "crypto-common",
+ "ctutils",
]
[[package]]
name = "displaydoc"
-version = "0.2.6"
+version = "0.2.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1ac70aa55017e108007fbaf5aa0f54b021c98f92ff8af59d42eda9da96e3dd4f"
+checksum = "c6232dd377dcc64799954cbd3a9bb882e9cdc1308ccd87b1c098f1fb2eaf82a8"
dependencies = [
"proc-macro2",
"quote",
- "syn 2.0.118",
+ "syn 3.0.6",
]
[[package]]
@@ -551,9 +649,15 @@ checksum = "5ac0893f103ae7bf50181323d748d505f27b6255777c28b502030bdaf8749f4c"
dependencies = [
"proc-macro2",
"quote",
- "syn 2.0.118",
+ "syn 2.0.119",
]
+[[package]]
+name = "either"
+version = "1.18.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "252afb9ae5eaa683babdc6a068b3f5726eb19e05070c731f9b2a23a7c3e8ed34"
+
[[package]]
name = "equivalent"
version = "1.0.2"
@@ -572,11 +676,10 @@ dependencies = [
[[package]]
name = "event-listener"
-version = "5.4.1"
+version = "5.4.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e13b66accf52311f30a0db42147dadea9850cb48cd070028831ae5f5d4b856ab"
+checksum = "5a23add41df1562121a9393cb065eab5146a1242410f23a644851e90cfd669d2"
dependencies = [
- "concurrent-queue",
"parking",
"pin-project-lite",
]
@@ -593,21 +696,31 @@ dependencies = [
[[package]]
name = "fastrand"
-version = "2.4.1"
+version = "2.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6"
+checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"
[[package]]
name = "fiat-crypto"
-version = "0.2.9"
+version = "0.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "28dea519a9695b9977216879a3ebfddf92f1c08c05d984f8996aecd6ecdc811d"
+checksum = "64cd1e32ddd350061ae6edb1b082d7c54915b5c672c389143b9a63403a109f24"
[[package]]
name = "find-msvc-tools"
-version = "0.1.9"
+version = "0.1.14"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
+checksum = "aedcfb3409746eddb02b9e19ebda1c3394f759a152e48ee875a0844d1b955484"
+
+[[package]]
+name = "flate2"
+version = "1.1.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e634e2e0ebac1ee034020da1ca582e17ffe4e0f5e985823721e168928136dcb"
+dependencies = [
+ "crc32fast",
+ "miniz_oxide",
+]
[[package]]
name = "fnv"
@@ -615,6 +728,33 @@ version = "1.0.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1"
+[[package]]
+name = "foreign-types"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d737d9aa519fb7b749cbc3b962edcf310a8dd1f4b67c91c4f83975dbdd17d965"
+dependencies = [
+ "foreign-types-macros",
+ "foreign-types-shared",
+]
+
+[[package]]
+name = "foreign-types-macros"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ea5190182e6915eb873ddbc16e23b711b6eb1f9c00a0d0a3a91b5f6228475225"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.6",
+]
+
+[[package]]
+name = "foreign-types-shared"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aa9a19cbb55df58761df49b23516a86d432839add4af60fc256da840f66ed35b"
+
[[package]]
name = "form_urlencoded"
version = "1.2.2"
@@ -631,10 +771,20 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "42703706b716c37f96a77aea830392ad231f44c9e9a67872fa5548707e11b11c"
[[package]]
-name = "futures"
-version = "0.3.33"
+name = "fslock"
+version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a88cf1f829d945f548cf8fec32c61b1f202b6d93b45848602fc02af4b12ad218"
+checksum = "04412b8935272e3a9bae6f48c7bfff74c2911f60525404edfdd28e49884c3bfb"
+dependencies = [
+ "libc",
+ "winapi",
+]
+
+[[package]]
+name = "futures"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9a31d2a3fbaaeb2af2368bbdd904aa8e812d3c04a1ee10d3171f52d556e5d0a3"
dependencies = [
"futures-channel",
"futures-core",
@@ -647,9 +797,9 @@ dependencies = [
[[package]]
name = "futures-channel"
-version = "0.3.33"
+version = "0.3.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "262590f4fe6afeb0bc83be1daa64e52657fe185690a958af7f3ad0e92085c5ae"
+checksum = "b1f9e3d69d39e4862ffed03ed071a76f9a13ba1d9109d355b0f0aa6b15e393c4"
dependencies = [
"futures-core",
"futures-sink",
@@ -657,15 +807,15 @@ dependencies = [
[[package]]
name = "futures-core"
-version = "0.3.33"
+version = "0.3.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2cd50c473c80f6d7c3670a752354b8e569b1a7cbfdc0419ec88e5edad85e0dc7"
+checksum = "92d699e522242e69e3003b94ecc1f960f3a5e015aa7c5d7486e65ad01dd94f5e"
[[package]]
name = "futures-executor"
-version = "0.3.33"
+version = "0.3.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6754879cc9f2c66f88c6e5c35344bb0bdb0708b0352b1201815667c7eabc7458"
+checksum = "031b47cf1a3c6cc8bc2fc76cd437f521619387907d469316e7c0bc278f1f5432"
dependencies = [
"futures-core",
"futures-task",
@@ -674,9 +824,9 @@ dependencies = [
[[package]]
name = "futures-io"
-version = "0.3.33"
+version = "0.3.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4577ecaa3c4f96589d473f679a71b596316f6641bc350038b962a5daf0085d7a"
+checksum = "53c0fa8157de1303bfffdaa1cc2a673bfffb60102f76b0ef4441659124373fed"
[[package]]
name = "futures-lite"
@@ -690,32 +840,32 @@ dependencies = [
[[package]]
name = "futures-macro"
-version = "0.3.33"
+version = "0.3.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2d6d3cde68c518367be28956066ddfef33813991b77a55005a69dae04bf3b10b"
+checksum = "9fb9654ba8355388abeb8dcb4fc62f511300867002afc858860463bdd9fe0c44"
dependencies = [
"proc-macro2",
"quote",
- "syn 2.0.118",
+ "syn 3.0.6",
]
[[package]]
name = "futures-sink"
-version = "0.3.33"
+version = "0.3.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e34418ac499d6305c2fb5ad0ed2f6ac998c5f8ca209b4510f7f94242c647e307"
+checksum = "1944426bf7d03f1d14f708785e4b33efd750b36d48a157b836b3efc15ede8e1d"
[[package]]
name = "futures-task"
-version = "0.3.33"
+version = "0.3.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b231ed28831efb4a61a08580c4bc233ec56bc009f4cd8f52da2c3cb97df0c109"
+checksum = "cd417de3d1d015fc3bfd2b1ea46dfc7bab72ef86f1cc7cc9c78e728b34a6d1fd"
[[package]]
name = "futures-util"
-version = "0.3.33"
+version = "0.3.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a77a90a256fce34da66415271e30f94ee91c57b04b8a2c042d9cf3220179deaa"
+checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc"
dependencies = [
"futures-channel",
"futures-core",
@@ -728,16 +878,6 @@ dependencies = [
"slab",
]
-[[package]]
-name = "generic-array"
-version = "0.14.7"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
-dependencies = [
- "typenum",
- "version_check",
-]
-
[[package]]
name = "getrandom"
version = "0.2.17"
@@ -745,20 +885,10 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
dependencies = [
"cfg-if",
+ "js-sys",
"libc",
"wasi",
-]
-
-[[package]]
-name = "getrandom"
-version = "0.3.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
-dependencies = [
- "cfg-if",
- "libc",
- "r-efi 5.3.0",
- "wasip2",
+ "wasm-bindgen",
]
[[package]]
@@ -768,9 +898,11 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099"
dependencies = [
"cfg-if",
+ "js-sys",
"libc",
- "r-efi 6.0.0",
- "rand_core 0.10.1",
+ "r-efi",
+ "rand_core",
+ "wasm-bindgen",
]
[[package]]
@@ -783,10 +915,16 @@ dependencies = [
]
[[package]]
-name = "h2"
-version = "0.4.15"
+name = "glob"
+version = "0.3.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6cb093c84e8bd9b188d4c4a8cb6579fc016968d14c99882163cd3ff402a4f155"
+checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b"
+
+[[package]]
+name = "h2"
+version = "0.4.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ef8e5e5a340588f4452631496976cf8636d4a7ecf600239fdc27615d2530bc16"
dependencies = [
"atomic-waker",
"bytes",
@@ -801,6 +939,34 @@ dependencies = [
"tracing",
]
+[[package]]
+name = "h3"
+version = "0.0.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "10872b55cfb02a821b69dc7cf8dc6a71d6af25eb9a79662bec4a9d016056b3be"
+dependencies = [
+ "bytes",
+ "fastrand",
+ "futures-util",
+ "http",
+ "pin-project-lite",
+ "tokio",
+]
+
+[[package]]
+name = "h3-quinn"
+version = "0.0.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b2e732c8d91a74731663ac8479ab505042fbf547b9a207213ab7fbcbfc4f8b4"
+dependencies = [
+ "bytes",
+ "futures",
+ "h3",
+ "quinn",
+ "tokio",
+ "tokio-util",
+]
+
[[package]]
name = "hash32"
version = "0.3.1"
@@ -827,15 +993,67 @@ dependencies = [
]
[[package]]
-name = "http"
-version = "1.4.2"
+name = "hkdf"
+version = "0.13.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6970f50e31d6fc17d3fa27329444bfa74e196cf62e95052a3f6fee181dba6425"
+checksum = "4aaa26c720c68b866f2c96ef5c1264b3e6f473fe5d4ce61cd44bbe913e553018"
+dependencies = [
+ "hmac",
+]
+
+[[package]]
+name = "hmac"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6303bc9732ae41b04cb554b844a762b4115a61bfaa81e3e83050991eeb56863f"
+dependencies = [
+ "digest",
+]
+
+[[package]]
+name = "hpke"
+version = "0.14.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a5324110b02044183df000f0bd7d2d7e61f1000631508627e77f63983b6fdffb"
+dependencies = [
+ "aead",
+ "aes-gcm",
+ "chacha20poly1305",
+ "hkdf",
+ "hybrid-array",
+ "rand_core",
+ "sha2",
+ "subtle",
+ "x25519-dalek",
+ "zeroize",
+]
+
+[[package]]
+name = "http"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "918d3568bebf352712bc2ef3d46a8bcf1a75b373be6539de198e9105cbbf9ce0"
dependencies = [
"bytes",
"itoa",
]
+[[package]]
+name = "http-body"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ca2a8f2913ee65f60facd6a5905613afaa448497a0230cc41ce022d93290bc2c"
+dependencies = [
+ "bytes",
+ "http",
+]
+
+[[package]]
+name = "httparse"
+version = "1.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87"
+
[[package]]
name = "hybrid-array"
version = "0.4.15"
@@ -846,10 +1064,44 @@ dependencies = [
]
[[package]]
-name = "icu_collections"
-version = "2.2.0"
+name = "hyper"
+version = "1.11.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2984d1cd16c883d7935b9e07e44071dca8d917fd52ecc02c04d5fa0b5a3f191c"
+checksum = "27b501faa50e7a26c3d3560ca625132f4078a17771f4810baf70475ae48cbe43"
+dependencies = [
+ "atomic-waker",
+ "bytes",
+ "futures-channel",
+ "futures-core",
+ "http",
+ "http-body",
+ "httparse",
+ "itoa",
+ "pin-project-lite",
+ "smallvec",
+ "tokio",
+ "want",
+]
+
+[[package]]
+name = "hyper-util"
+version = "0.1.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "96547c2556ec9d12fb1578c4eaf448b04993e7fb79cbaad930a656880a6bdfa0"
+dependencies = [
+ "bytes",
+ "http",
+ "http-body",
+ "hyper",
+ "pin-project-lite",
+ "tokio",
+]
+
+[[package]]
+name = "icu_collections"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fa68d21081c4a05d5a901a1c62add574c77048b6a1c67be3b50ce0b60d4ca513"
dependencies = [
"displaydoc",
"potential_utf",
@@ -861,9 +1113,9 @@ dependencies = [
[[package]]
name = "icu_locale_core"
-version = "2.2.0"
+version = "2.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "92219b62b3e2b4d88ac5119f8904c10f8f61bf7e95b640d25ba3075e6cac2c29"
+checksum = "d56e28588da92eee5c3201a6eff33fabdd49b62269c8938d4ff050ce4d900deb"
dependencies = [
"displaydoc",
"litemap",
@@ -874,9 +1126,9 @@ dependencies = [
[[package]]
name = "icu_normalizer"
-version = "2.2.0"
+version = "2.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c56e5ee99d6e3d33bd91c5d85458b6005a22140021cc324cea84dd0e72cff3b4"
+checksum = "12f9cf5f235641ed274641dd81c3f28d870e276763d0797aeeab72317b1c646f"
dependencies = [
"icu_collections",
"icu_normalizer_data",
@@ -888,16 +1140,17 @@ dependencies = [
[[package]]
name = "icu_normalizer_data"
-version = "2.2.0"
+version = "2.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "da3be0ae77ea334f4da67c12f149704f19f81d1adf7c51cf482943e84a2bad38"
+checksum = "1563da1ed3e0b3bf3d74c9b85917ac9c56464d2f57242270c09c9e752f8021a0"
[[package]]
name = "icu_properties"
-version = "2.2.0"
+version = "2.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bee3b67d0ea5c2cca5003417989af8996f8604e34fb9ddf96208a033901e70de"
+checksum = "7e7ca276ad3145661a65914e6daf131ca5120cd3dcee8f8f3214b8875184a148"
dependencies = [
+ "displaydoc",
"icu_collections",
"icu_locale_core",
"icu_properties_data",
@@ -908,15 +1161,15 @@ dependencies = [
[[package]]
name = "icu_properties_data"
-version = "2.2.0"
+version = "2.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8e2bbb201e0c04f7b4b3e14382af113e17ba4f63e2c9d2ee626b720cbce54a14"
+checksum = "e590f038c1464a96894fd6d10127e90a8be4509f56ff7ecef851b15cee0b7caa"
[[package]]
name = "icu_provider"
-version = "2.2.0"
+version = "2.3.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "139c4cf31c8b5f33d7e199446eff9c1e02decfc2f0eec2c8d71f65befa45b421"
+checksum = "d27bbb9d3abbefac45d55f647c9de1d44aafcd1186eb91879afef17c396c3e73"
dependencies = [
"displaydoc",
"icu_locale_core",
@@ -950,9 +1203,9 @@ dependencies = [
[[package]]
name = "indexmap"
-version = "2.14.0"
+version = "2.14.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
+checksum = "cc4e190f5d26ca7051642629da2c52fc03bde85a03197c99408dcd291734c855"
dependencies = [
"equivalent",
"hashbrown",
@@ -969,9 +1222,18 @@ dependencies = [
[[package]]
name = "ipnet"
-version = "2.12.0"
+version = "2.12.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d98f6fed1fde3f8c21bc40a1abb88dd75e67924f9cffc3ef95607bad8017f8e2"
+checksum = "791930b43c0d5973160d90a8f3894509f2b273430f5c5c73b668636d0287c5c0"
+
+[[package]]
+name = "itertools"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186"
+dependencies = [
+ "either",
+]
[[package]]
name = "itoa"
@@ -991,15 +1253,25 @@ dependencies = [
[[package]]
name = "js-sys"
-version = "0.3.103"
+version = "0.3.105"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "53b44bfcdb3f8d5837a46dae1ca9660a837176eee74a28b229bc626816589102"
+checksum = "ce57d20d1ea864ce2ac172ab472d409214f4fd359f0b2a2775abdf522e2af99e"
dependencies = [
"cfg-if",
"futures-util",
"wasm-bindgen",
]
+[[package]]
+name = "keccak"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d8f198d1db720e4940b5a493201d199d9f24f568f8f746bd13706243a2f71598"
+dependencies = [
+ "cfg-if",
+ "cpufeatures",
+]
+
[[package]]
name = "lazy_static"
version = "1.5.0"
@@ -1012,6 +1284,16 @@ version = "0.2.189"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
+[[package]]
+name = "libloading"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d7c4b02199fee7c5d21a5ae7d8cfa79a6ef5bb2fc834d6e9058e89c825efdc55"
+dependencies = [
+ "cfg-if",
+ "windows-link",
+]
+
[[package]]
name = "libloading"
version = "0.9.0"
@@ -1030,9 +1312,9 @@ checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
[[package]]
name = "litemap"
-version = "0.8.2"
+version = "0.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "92daf443525c4cce67b150400bc2316076100ce0b3686209eb8cf3c31612e6f0"
+checksum = "47d9d19d1d6efa0109d2f65ff4c85cddd50bd572e5a00127ab10987290bcefae"
[[package]]
name = "lock_api"
@@ -1045,9 +1327,15 @@ dependencies = [
[[package]]
name = "log"
-version = "0.4.33"
+version = "0.4.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
+checksum = "f9f8bd3e56ce4dfc153cf470fffbfa98c7620958b312ca5c3a4b8d5181fd13c6"
+
+[[package]]
+name = "lru-slab"
+version = "0.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4050469837a6ff301cd14c1f8f24f88549e6d548f24f64e2148eb0f72cebc51f"
[[package]]
name = "lru_time_cache"
@@ -1063,9 +1351,9 @@ checksum = "0ca88d725a0a943b096803bd34e73a4437208b6077654cc4ecb2947a5f91618d"
[[package]]
name = "md-5"
-version = "0.10.6"
+version = "0.11.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d89e7ee0cfbedfc4da3340218492196241d89eefb6dab27de5df917a6d2e78cf"
+checksum = "69b6441f590336821bb897fb28fc622898ccceb1d6cea3fde5ea86b090c4de98"
dependencies = [
"cfg-if",
"digest",
@@ -1084,10 +1372,20 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
[[package]]
-name = "mio"
-version = "1.2.1"
+name = "miniz_oxide"
+version = "0.9.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "02bd0af71c67b473010cbbc60715ee815645a4dc942899111f494b4b737d6fda"
+checksum = "b63fbc4a50860e98e7b2aa7804ded1db5cbc3aff9193adaff57a6931bf7c4b4c"
+dependencies = [
+ "adler2",
+ "simd-adler32",
+]
+
+[[package]]
+name = "mio"
+version = "1.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4b18443e9c262bfe8fa82f51666e2642c53393f7e5c27b3e1aeab922cff5b9d8"
dependencies = [
"libc",
"wasi",
@@ -1100,12 +1398,18 @@ version = "0.31.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cf20d2fde8ff38632c426f1165ed7436270b44f199fc55284c38276f9db47c3d"
dependencies = [
- "bitflags 2.13.0",
+ "bitflags 2.13.2",
"cfg-if",
"cfg_aliases",
"libc",
]
+[[package]]
+name = "nohash-hasher"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2bf50223579dc7cdcfb3bfcacf7069ff68243f8c363f62ffa99cf000a6b9c451"
+
[[package]]
name = "nom"
version = "7.1.3"
@@ -1165,6 +1469,17 @@ version = "1.21.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+[[package]]
+name = "openssl-macros"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a948666b637a0f465e8564c73e89d4dde00d72d4d473cc972f390fc3dcee7d9c"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
[[package]]
name = "oslog"
version = "0.2.0"
@@ -1226,7 +1541,7 @@ checksum = "c96395f0a926bc13b1c17622aaddda1ecb55d49c8f1bf9777e4d877800a43f8b"
dependencies = [
"proc-macro2",
"quote",
- "syn 2.0.118",
+ "syn 2.0.119",
]
[[package]]
@@ -1258,7 +1573,7 @@ version = "0.9.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6e2d0073b297041425c7c3df6eb4792d598a15323fe63346852b092eca02904c"
dependencies = [
- "cpufeatures 0.3.1",
+ "cpufeatures",
"universal-hash",
]
@@ -1269,15 +1584,15 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f0fa31d631f2b2cb2a544d0aa321ce847a94764d701ca2becc411138b93d49cd"
dependencies = [
"cpubits",
- "cpufeatures 0.3.1",
+ "cpufeatures",
"universal-hash",
]
[[package]]
name = "potential_utf"
-version = "0.1.5"
+version = "0.1.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0103b1cef7ec0cf76490e969665504990193874ea05c85ff9bab8b911d0a0564"
+checksum = "d83eb9bc6d8e5cf568e7a1101d60ee05e81ed50ea106026f3d18deeb046d7661"
dependencies = [
"zerovec",
]
@@ -1288,38 +1603,80 @@ version = "0.2.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "439ee305def115ba05938db6eb1644ff94165c5ab5e9420d1c1bcedbba909391"
-[[package]]
-name = "ppv-lite86"
-version = "0.2.21"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9"
-dependencies = [
- "zerocopy",
-]
-
[[package]]
name = "proc-macro2"
-version = "1.0.106"
+version = "1.0.107"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
dependencies = [
"unicode-ident",
]
[[package]]
-name = "quote"
-version = "1.0.46"
+name = "quinn"
+version = "0.11.12"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368"
+checksum = "4051e23e9185c255a7e33ef59cdbca87a22d359052eecd22fc6b901fb37d9d11"
dependencies = [
- "proc-macro2",
+ "bytes",
+ "cfg_aliases",
+ "futures-io",
+ "pin-project-lite",
+ "quinn-proto",
+ "quinn-udp",
+ "rustc-hash",
+ "rustls",
+ "socket2",
+ "thiserror",
+ "tokio",
+ "tracing",
+ "web-time",
]
[[package]]
-name = "r-efi"
-version = "5.3.0"
+name = "quinn-proto"
+version = "0.11.18"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f"
+checksum = "a9746dbde176634f4f2f1faf2404e30a31b2bc1e9cafb5329c95d8177a18c9fc"
+dependencies = [
+ "bytes",
+ "getrandom 0.4.3",
+ "lru-slab",
+ "rand",
+ "rand_pcg",
+ "ring",
+ "rustc-hash",
+ "rustls",
+ "rustls-pki-types",
+ "slab",
+ "thiserror",
+ "tinyvec",
+ "tracing",
+ "web-time",
+]
+
+[[package]]
+name = "quinn-udp"
+version = "0.5.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "35a133f956daabe89a61a685c2649f13d82d5aa4bd5d12d1277e1072a21c0694"
+dependencies = [
+ "cfg_aliases",
+ "libc",
+ "once_cell",
+ "socket2",
+ "tracing",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
[[package]]
name = "r-efi"
@@ -1329,48 +1686,13 @@ checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
[[package]]
name = "rand"
-version = "0.9.5"
+version = "0.10.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b9ef1d0d795eb7d84685bca4f72f3649f064e6641543d3a8c415898726a57b41"
-dependencies = [
- "rand_chacha",
- "rand_core 0.9.5",
-]
-
-[[package]]
-name = "rand"
-version = "0.10.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c7f5fa3a058cd35567ef9bfa5e75732bee0f9e4c55fa90477bef2dfcdbc4be80"
+checksum = "65c9fb96cbc91e3478eaae79a69fcd3f1ae4ad052e471fe6732fff548984b4af"
dependencies = [
"chacha20",
"getrandom 0.4.3",
- "rand_core 0.10.1",
-]
-
-[[package]]
-name = "rand_chacha"
-version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d3022b5f1df60f26e1ffddd6c66e8aa15de382ae63b3a0c1bfc0e4d3e3f325cb"
-dependencies = [
- "ppv-lite86",
- "rand_core 0.9.5",
-]
-
-[[package]]
-name = "rand_core"
-version = "0.6.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c"
-
-[[package]]
-name = "rand_core"
-version = "0.9.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "76afc826de14238e6e8c374ddcc1fa19e374fd8dd986b0d2af0d02377261d83c"
-dependencies = [
- "getrandom 0.3.4",
+ "rand_core",
]
[[package]]
@@ -1380,10 +1702,19 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69"
[[package]]
-name = "rcgen"
-version = "0.14.8"
+name = "rand_pcg"
+version = "0.10.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "57f6d249aad744e274e682777a50283a225a32705394ee6d5fcc01efa25e4055"
+checksum = "caa0f4137e1c0a72f4c651489402276c8e8e1cf081f3b0ba156d2cbeef09e86a"
+dependencies = [
+ "rand_core",
+]
+
+[[package]]
+name = "rcgen"
+version = "0.14.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8774e05a7d0de114588e6a28fe7e71694b82614ed569d86d8b389dfbc98b8ad8"
dependencies = [
"ring",
"rustls-pki-types",
@@ -1398,15 +1729,29 @@ version = "0.5.18"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
dependencies = [
- "bitflags 2.13.0",
+ "bitflags 2.13.2",
+]
+
+[[package]]
+name = "regex"
+version = "1.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
]
[[package]]
name = "regex-automata"
-version = "0.4.15"
+version = "0.4.18"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1f388202e4b80542a0921078cc23b6333bcf1409c1e3f86404cae4766a6131db"
+checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2"
dependencies = [
+ "aho-corasick",
+ "memchr",
"regex-syntax",
]
@@ -1430,6 +1775,12 @@ dependencies = [
"windows-sys 0.52.0",
]
+[[package]]
+name = "rustc-hash"
+version = "2.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
+
[[package]]
name = "rustc_version"
version = "0.4.1"
@@ -1450,11 +1801,11 @@ dependencies = [
[[package]]
name = "rustix"
-version = "1.1.4"
+version = "1.1.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b6fe4565b9518b83ef4f91bb47ce29620ca828bd32cb7e408f0062e9930ba190"
+checksum = "891efababe418670775f199f0d233d84843c227a0949a883ce15b37c78d6629d"
dependencies = [
- "bitflags 2.13.0",
+ "bitflags 2.13.2",
"errno",
"libc",
"linux-raw-sys",
@@ -1463,32 +1814,33 @@ dependencies = [
[[package]]
name = "rustls"
-version = "0.23.43"
-source = "git+https://github.com/OneVCore/rustls?branch=vcore%2Freality-0.23#df261c84cbac4f708e63ac8644ce70daa90d771c"
+version = "0.23.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0d41d731c7d2f962d1ccc364cec258de3c0e93b38c2fb3ba97ac74513048d634"
dependencies = [
"once_cell",
"ring",
"rustls-pki-types",
"rustls-webpki",
"subtle",
- "x25519-dalek",
"zeroize",
]
[[package]]
name = "rustls-pki-types"
-version = "1.15.0"
+version = "1.15.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "764899a24af3980067ee14bc143654f297b22eaebfe3c7b6b211920a5a59b046"
+checksum = "2f4925028c7eb5d1fcdaf196971378ed9d2c1c4efc7dc5d011256f76c99c0a96"
dependencies = [
+ "web-time",
"zeroize",
]
[[package]]
name = "rustls-webpki"
-version = "0.103.13"
+version = "0.103.15"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "61c429a8649f110dddef65e2a5ad240f747e85f7758a6bccc7e5777bd33f756e"
+checksum = "f3c3cf1d8b1e7d4927e2d154c3fcb02979afb9939629c62cd9048d4f07b60ac2"
dependencies = [
"ring",
"rustls-pki-types",
@@ -1521,7 +1873,7 @@ checksum = "9b68e2ea526d9fb32f23ca8894fb5da9e743f34c2f41701f0501dc8a25c4b343"
dependencies = [
"proc-macro2",
"quote",
- "syn 3.0.3",
+ "syn 3.0.6",
]
[[package]]
@@ -1542,9 +1894,9 @@ dependencies = [
[[package]]
name = "serde"
-version = "1.0.228"
+version = "1.0.229"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
dependencies = [
"serde_core",
"serde_derive",
@@ -1552,22 +1904,22 @@ dependencies = [
[[package]]
name = "serde_core"
-version = "1.0.228"
+version = "1.0.229"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
dependencies = [
"serde_derive",
]
[[package]]
name = "serde_derive"
-version = "1.0.228"
+version = "1.0.229"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
dependencies = [
"proc-macro2",
"quote",
- "syn 2.0.118",
+ "syn 3.0.6",
]
[[package]]
@@ -1609,23 +1961,35 @@ dependencies = [
]
[[package]]
-name = "sha2"
-version = "0.10.9"
+name = "sha1"
+version = "0.11.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
+checksum = "aacc4cc499359472b4abe1bf11d0b12e688af9a805fa5e3016f9a386dc2d0214"
dependencies = [
"cfg-if",
- "cpufeatures 0.2.17",
+ "cpufeatures",
+ "digest",
+]
+
+[[package]]
+name = "sha2"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "446ba717509524cb3f22f17ecc096f10f4822d76ab5c0b9822c5f9c284e825f4"
+dependencies = [
+ "cfg-if",
+ "cpufeatures",
"digest",
]
[[package]]
name = "shadowsocks"
version = "1.25.0"
-source = "git+https://github.com/shadowsocks/shadowsocks-rust.git?rev=ab388c7466d21f979430e33cc9ef10e22fb05955#ab388c7466d21f979430e33cc9ef10e22fb05955"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e2065b026dbe4f47048eca384adf07f693bf901050d80abd3adb7b2422709b2d"
dependencies = [
"aes",
- "base64 0.23.1",
+ "base64",
"blake3",
"byte_string",
"bytes",
@@ -1637,7 +2001,7 @@ dependencies = [
"lru_time_cache",
"percent-encoding",
"pin-project",
- "rand 0.10.2",
+ "rand",
"sealed",
"sendfd",
"serde",
@@ -1667,9 +2031,26 @@ dependencies = [
"bytes",
"cfg-if",
"chacha20poly1305",
- "rand 0.10.2",
+ "rand",
]
+[[package]]
+name = "shake"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09057cb2149ad4cbd2da1e26b351f9a4c354219421229c69c3063e6f61947c4a"
+dependencies = [
+ "digest",
+ "keccak",
+ "sponge-cursor",
+]
+
+[[package]]
+name = "shlex"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
+
[[package]]
name = "shlex"
version = "2.0.1"
@@ -1686,6 +2067,12 @@ dependencies = [
"libc",
]
+[[package]]
+name = "simd-adler32"
+version = "0.3.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea"
+
[[package]]
name = "slab"
version = "0.4.12"
@@ -1694,29 +2081,29 @@ checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
[[package]]
name = "smallvec"
-version = "1.15.2"
+version = "1.16.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90"
+checksum = "ba467056f1b547ed52077911161fc86985becbc60e8e1857c8a144dab0def891"
[[package]]
name = "smoltcp"
-version = "0.13.1"
+version = "0.14.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5f73d40463bba65efc9adc6370b56df76d563cc46e2482bba58351b4afb7535e"
+checksum = "b6f8b28ad56c6e35524a37dd492af5d1a47e31e1a4d175cd12f89c075f01980f"
dependencies = [
"bitflags 1.3.2",
"byteorder",
"cfg-if",
- "defmt 0.3.100",
+ "defmt",
"heapless",
"managed",
]
[[package]]
name = "socket2"
-version = "0.6.4"
+version = "0.6.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "52d1cfed4120b4d927bf7c0f86d2087a4a7d6027c906d9f9d525a80573b9be51"
+checksum = "c3d1e2c7f27f8d4cb10542a02c49005dbd6e93095799d6f3be745fae9f8fedd4"
dependencies = [
"libc",
"windows-sys 0.61.2",
@@ -1731,12 +2118,24 @@ dependencies = [
"lock_api",
]
+[[package]]
+name = "sponge-cursor"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3a0219bd7d979d58245a4f41f695e1ac9f8befdffadd7f61f1bae9e39abc6620"
+
[[package]]
name = "stable_deref_trait"
version = "1.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
+[[package]]
+name = "static_assertions"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2eb9349b6444b326872e140eb1cf5e7c522154d69e7a0ffb0fb81c06b37543f"
+
[[package]]
name = "subtle"
version = "2.6.1"
@@ -1745,9 +2144,9 @@ checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"
[[package]]
name = "syn"
-version = "2.0.118"
+version = "2.0.119"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
dependencies = [
"proc-macro2",
"quote",
@@ -1756,9 +2155,9 @@ dependencies = [
[[package]]
name = "syn"
-version = "3.0.3"
+version = "3.0.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3"
+checksum = "8593e8e72159ed2257d083c7a454a85cbf854f37a0966d8d483aff8c8a3ebcee"
dependencies = [
"proc-macro2",
"quote",
@@ -1773,7 +2172,18 @@ checksum = "728a70f3dbaf5bab7f0c4b1ac8d7ae5ea60a4b5549c8a5914361c99147a709d2"
dependencies = [
"proc-macro2",
"quote",
- "syn 2.0.118",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "synstructure"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "901704edd0dfe137f1987838ee4f259e4e063c31371bdb423f7ae38ec6f77f02"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.6",
]
[[package]]
@@ -1791,22 +2201,22 @@ dependencies = [
[[package]]
name = "thiserror"
-version = "2.0.19"
+version = "2.0.20"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "09a43598840e33d5b0331f38c5e30d13bb11c11210a4b58f0d9b18a5a5eefcd9"
+checksum = "ec86235f5fcc2a73650310756d2ac5b138a5780bbbdfae3eeccec992c435ba4f"
dependencies = [
"thiserror-impl",
]
[[package]]
name = "thiserror-impl"
-version = "2.0.19"
+version = "2.0.20"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "43cbfe0cf76104d42a574802844187e84a305e531ed54455f11fbde0f10541cd"
+checksum = "bc04cd3e1236dd4a98afca4569f2deb3f120e5422a4023be2cb683f8486292af"
dependencies = [
"proc-macro2",
"quote",
- "syn 3.0.3",
+ "syn 3.0.6",
]
[[package]]
@@ -1841,19 +2251,25 @@ dependencies = [
[[package]]
name = "tinystr"
-version = "0.8.3"
+version = "0.8.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c8323304221c2a851516f22236c5722a72eaa19749016521d6dff0824447d96d"
+checksum = "b1e27c91459209c2986af3dcf603a5a74a4368754ce37414f59acc971167f643"
dependencies = [
"displaydoc",
"zerovec",
]
[[package]]
-name = "tokio"
-version = "1.52.3"
+name = "tinyvec"
+version = "1.13.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8fc7f01b389ac15039e4dc9531aa973a135d7a4135281b12d7c1bc79fd57fffe"
+checksum = "fd3ca314f692efd6c868f8408f53fe444634a845f96c028b97d35f6a1f79f0ee"
+
+[[package]]
+name = "tokio"
+version = "1.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "202caea871b69668250d242070849eb495be178ed697a3e98aebce5bc81a0bed"
dependencies = [
"bytes",
"libc",
@@ -1866,22 +2282,32 @@ dependencies = [
"windows-sys 0.61.2",
]
+[[package]]
+name = "tokio-boring"
+version = "5.2.0"
+source = "git+https://github.com/OneXray/boring?branch=release#d5a5d41850886aef5b269015130ee6d6eb2129ba"
+dependencies = [
+ "boring",
+ "boring-sys",
+ "tokio",
+]
+
[[package]]
name = "tokio-macros"
-version = "2.7.0"
+version = "2.7.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "385a6cb71ab9ab790c5fe8d67f1645e6c450a7ce006a33de03daa956cf70a496"
+checksum = "78773a2a397f451582ce068015985c33193cf6dea8b74d2a639fe457b2f07b0e"
dependencies = [
"proc-macro2",
"quote",
- "syn 2.0.118",
+ "syn 3.0.6",
]
[[package]]
name = "tokio-rustls"
-version = "0.26.4"
+version = "0.26.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1729aa945f29d91ba541258c8df89027d5792d85a8841fb65e8bf0f4ede4ef61"
+checksum = "b0c85f2c3ef0b1cd58b36682f4b17aaa995f0e5db534d85692b4903abce21f67"
dependencies = [
"rustls",
"tokio",
@@ -1905,15 +2331,29 @@ dependencies = [
]
[[package]]
-name = "tokio-util"
-version = "0.7.18"
+name = "tokio-tungstenite"
+version = "0.30.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9ae9cec805b01e8fc3fd2fe289f89149a9b66dd16786abd8b19cfa7b48cb0098"
+checksum = "17a073bfed563fa236697a068031408a93cd9522e08abf9933ead3e73411bd71"
+dependencies = [
+ "futures-util",
+ "log",
+ "tokio",
+ "tungstenite",
+]
+
+[[package]]
+name = "tokio-util"
+version = "0.7.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "494815d09bf52b5548659851081238f0ca39ff638363907596da739561c62c52"
dependencies = [
"bytes",
"futures-core",
+ "futures-io",
"futures-sink",
"futures-util",
+ "libc",
"pin-project-lite",
"tokio",
]
@@ -1937,7 +2377,7 @@ checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da"
dependencies = [
"proc-macro2",
"quote",
- "syn 2.0.118",
+ "syn 2.0.119",
]
[[package]]
@@ -1957,9 +2397,15 @@ checksum = "b19a4867a870f6edc4c283f2b455804b1879c0baf0e642f26b03ed8ee262d9d3"
dependencies = [
"proc-macro2",
"quote",
- "syn 2.0.118",
+ "syn 2.0.119",
]
+[[package]]
+name = "try-lock"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"
+
[[package]]
name = "tun"
version = "0.8.14"
@@ -1978,6 +2424,22 @@ dependencies = [
"wintun-bindings",
]
+[[package]]
+name = "tungstenite"
+version = "0.30.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e48ac77174b19c110a50ab2128b24215ac9cb40e0e12e093fb602d175c569d22"
+dependencies = [
+ "bytes",
+ "data-encoding",
+ "http",
+ "httparse",
+ "log",
+ "rand",
+ "sha1",
+ "thiserror",
+]
+
[[package]]
name = "typenum"
version = "1.20.1"
@@ -1986,9 +2448,9 @@ checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20"
[[package]]
name = "unicode-ident"
-version = "1.0.24"
+version = "1.0.26"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+checksum = "d245f478577f809a851594d02313b640fb437e0bb33866753cff937863096954"
[[package]]
name = "universal-hash"
@@ -1996,7 +2458,7 @@ version = "0.6.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f4987bdc12753382e0bec4a65c50738ffaabc998b9cdd1f952fb5f39b0048a96"
dependencies = [
- "crypto-common 0.2.2",
+ "crypto-common",
"ctutils",
]
@@ -2038,9 +2500,9 @@ checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
[[package]]
name = "uuid"
-version = "1.23.4"
+version = "1.26.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bf80a72845275afea99e7f2b434723d3bc7e38470fcd1c7ed39a599c73319a53"
+checksum = "2ef6dac1e96601b4fb3acccccff2139741fcb757cb9a36089bf5be91cfb285ce"
dependencies = [
"js-sys",
"serde_core",
@@ -2054,41 +2516,70 @@ dependencies = [
"aes",
"arc-swap",
"async-trait",
- "base64 0.22.1",
+ "base64",
+ "blake2",
"blake3",
+ "boring",
+ "boring-sys",
"bytes",
+ "crc32fast",
+ "foreign-types",
"futures-util",
"h2",
+ "h3",
+ "h3-quinn",
+ "hpke",
"http",
+ "httparse",
+ "hyper",
+ "hyper-util",
"idna",
"libc",
"log",
"md-5",
"oslog",
- "rand 0.9.5",
+ "quinn",
+ "quinn-proto",
+ "rand",
"rcgen",
"regex-automata",
+ "ring",
"rustls",
"serde",
"serde_json",
"serde_yaml_ng",
"sha2",
"shadowsocks",
+ "shake",
"socket2",
"tempfile",
"thiserror",
"tokio",
+ "tokio-boring",
"tokio-rustls",
+ "tokio-tungstenite",
"tokio-util",
"tracing",
"tun",
"url",
"uuid",
+ "vcore-blake3-raw",
"vcore-netstack",
"webpki-roots",
"windows",
"windows-collections",
"windows-core",
+ "yamux",
+ "zeroize",
+]
+
+[[package]]
+name = "vcore-blake3-raw"
+version = "0.1.0"
+dependencies = [
+ "blake3",
+ "cc",
+ "serde_json",
]
[[package]]
@@ -2104,10 +2595,13 @@ dependencies = [
]
[[package]]
-name = "version_check"
-version = "0.9.5"
+name = "want"
+version = "0.3.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
+checksum = "bfa7760aed19e106de2c7c0b581b509f2f25d3dacaf737cb82ac61bc6d760b0e"
+dependencies = [
+ "try-lock",
+]
[[package]]
name = "wasi"
@@ -2115,20 +2609,11 @@ version = "0.11.1+wasi-snapshot-preview1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
-[[package]]
-name = "wasip2"
-version = "1.0.4+wasi-0.2.12"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b67efb37e106e55ce722a510d6b5f9c17f083e5fc79afc2badeb12cc313d9487"
-dependencies = [
- "wit-bindgen",
-]
-
[[package]]
name = "wasm-bindgen"
-version = "0.2.126"
+version = "0.2.128"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4b067c0c11094aef6b7a801c1e34a26affafdf3d051dba08456b868789aaf9a4"
+checksum = "aecb87a33d3b0c5e3b7aa46336eaf486cffafbd281b195e4c8b80d50df2351bf"
dependencies = [
"cfg-if",
"once_cell",
@@ -2139,9 +2624,9 @@ dependencies = [
[[package]]
name = "wasm-bindgen-macro"
-version = "0.2.126"
+version = "0.2.128"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "167ce5e579f6bcf889c4f7175a8a5a585de84e8ff93976ce393efa5f2837aab1"
+checksum = "a690d511e3c1a8b3a55e33511e3c2c00c78415cd23650f32b808627f5696b9ed"
dependencies = [
"quote",
"wasm-bindgen-macro-support",
@@ -2149,35 +2634,67 @@ dependencies = [
[[package]]
name = "wasm-bindgen-macro-support"
-version = "0.2.126"
+version = "0.2.128"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f3997c7839262f4ef12cf90b818d6340c18e80f263f1a94bf157d0ec4420380e"
+checksum = "411e4887f0071ef2d2164a9d5fdf2d20efbef78fccd3a78b0c10a1dc5295e48a"
dependencies = [
"bumpalo",
"proc-macro2",
"quote",
- "syn 2.0.118",
+ "syn 3.0.6",
"wasm-bindgen-shared",
]
[[package]]
name = "wasm-bindgen-shared"
-version = "0.2.126"
+version = "0.2.128"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dc1b4cb0cc549fcf58d7dfc081778139b3d283a081644e833e84682ad71cea24"
+checksum = "81941cd78d0c92026c33e5e01312845a4cb1e9af3407f9134b100dd03144103e"
dependencies = [
"unicode-ident",
]
[[package]]
-name = "webpki-roots"
-version = "1.0.8"
+name = "web-time"
+version = "1.1.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bf85cb06032201fa7c6f829d7db5a7e5aa45bcc0655327713065f6f0576731bf"
+checksum = "5a6580f308b1fad9207618087a65c04e7a10bc77e02c8e84e9b00dd4b12fa0bb"
+dependencies = [
+ "js-sys",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "webpki-roots"
+version = "1.0.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7dcd9d09a39985f5344844e66b0c530a33843579125f23e21e9f0f220850f22a"
dependencies = [
"rustls-pki-types",
]
+[[package]]
+name = "winapi"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419"
+dependencies = [
+ "winapi-i686-pc-windows-gnu",
+ "winapi-x86_64-pc-windows-gnu",
+]
+
+[[package]]
+name = "winapi-i686-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6"
+
+[[package]]
+name = "winapi-x86_64-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
+
[[package]]
name = "windows"
version = "0.62.2"
@@ -2231,7 +2748,7 @@ checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
dependencies = [
"proc-macro2",
"quote",
- "syn 2.0.118",
+ "syn 2.0.119",
]
[[package]]
@@ -2242,7 +2759,7 @@ checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
dependencies = [
"proc-macro2",
"quote",
- "syn 2.0.118",
+ "syn 2.0.119",
]
[[package]]
@@ -2446,38 +2963,32 @@ checksum = "d6bbff5f0aada427a1e5a6da5f1f98158182f26556f345ac9e04d36d0ebed650"
[[package]]
name = "wintun-bindings"
-version = "0.7.39"
+version = "0.7.40"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fc4494d02357537af05cf526be7b817a51752b688a78926af57379abd840d911"
+checksum = "e4316764300a7eb4aecf4770c81ae629ff1161b54905d48721a6832fd296ce5f"
dependencies = [
"blocking",
"futures",
- "libloading",
+ "libloading 0.9.0",
"log",
"thiserror",
"windows-sys 0.61.2",
]
-[[package]]
-name = "wit-bindgen"
-version = "0.57.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e"
-
[[package]]
name = "writeable"
-version = "0.6.3"
+version = "0.6.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1ffae5123b2d3fc086436f8834ae3ab053a283cfac8fe0a0b8eaae044768a4c4"
+checksum = "3ad82d2a33cdc9674dc7465672f271e096168fcdbe0f799d9e6db8c5892679dc"
[[package]]
name = "x25519-dalek"
-version = "2.0.1"
+version = "3.0.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c7e468321c81fb07fa7f4c636c3972b9100f0346e5b6a9f2bd0603a52f7ed277"
+checksum = "e7e8131a03190127fb2263afc72b322ecadae46b6ff8c6f399ff5d02f5559af6"
dependencies = [
"curve25519-dalek",
- "rand_core 0.6.4",
+ "rand_core",
"zeroize",
]
@@ -2499,6 +3010,21 @@ dependencies = [
"time",
]
+[[package]]
+name = "yamux"
+version = "0.14.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4f4e661d6ba6f09a768e31c6f3d88f9fac596ad5d376515d598a37b62d220b34"
+dependencies = [
+ "futures",
+ "log",
+ "nohash-hasher",
+ "parking_lot",
+ "pin-project",
+ "static_assertions",
+ "web-time",
+]
+
[[package]]
name = "yasna"
version = "0.6.0"
@@ -2522,34 +3048,14 @@ dependencies = [
[[package]]
name = "yoke-derive"
-version = "0.8.2"
+version = "0.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "de844c262c8848816172cef550288e7dc6c7b7814b4ee56b3e1553f275f1858e"
+checksum = "33811428bee40dbceb6d545e95754741d17a6aef9a4849f0fd62e2ba4f412a78"
dependencies = [
"proc-macro2",
"quote",
- "syn 2.0.118",
- "synstructure",
-]
-
-[[package]]
-name = "zerocopy"
-version = "0.8.54"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b7cbbc0a705a0fd05cc3676525980d2bf5a9bc4adac6d6475209a7887cf59d19"
-dependencies = [
- "zerocopy-derive",
-]
-
-[[package]]
-name = "zerocopy-derive"
-version = "0.8.54"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e2e817b7b52d0c7358d3246da9d69935ebb18116b2b102b4230dac079b4862f5"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn 2.0.118",
+ "syn 3.0.6",
+ "synstructure 0.14.0",
]
[[package]]
@@ -2563,14 +3069,14 @@ dependencies = [
[[package]]
name = "zerofrom-derive"
-version = "0.1.7"
+version = "0.1.8"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "11532158c46691caf0f2593ea8358fed6bbf68a0315e80aae9bd41fbade684a1"
+checksum = "f75b4683f6c7f45248d4d64056a24298c6281e0993356d7d1b4a1a962ef10d4a"
dependencies = [
"proc-macro2",
"quote",
- "syn 2.0.118",
- "synstructure",
+ "syn 3.0.6",
+ "synstructure 0.14.0",
]
[[package]]
@@ -2590,14 +3096,14 @@ checksum = "3c50655cbb0fe3fc43170059e702f1ce5e19b84cec58dc87b037a09935c2f328"
dependencies = [
"proc-macro2",
"quote",
- "syn 2.0.118",
+ "syn 2.0.119",
]
[[package]]
name = "zerotrie"
-version = "0.2.4"
+version = "0.2.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0f9152d31db0792fa83f70fb2f83148effb5c1f5b8c7686c3459e361d9bc20bf"
+checksum = "4ea269c3bd32f0a32c321907a2ae912ba6f4649bb0fc764a15627e99a7095a3f"
dependencies = [
"displaydoc",
"yoke",
@@ -2606,9 +3112,9 @@ dependencies = [
[[package]]
name = "zerovec"
-version = "0.11.6"
+version = "0.11.8"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "90f911cbc359ab6af17377d242225f4d75119aec87ea711a880987b18cd7b239"
+checksum = "bb0464e17806c1d976d5cba29399c7f08e516e279e2ba493f63123b5fca67dd8"
dependencies = [
"yoke",
"zerofrom",
@@ -2617,17 +3123,17 @@ dependencies = [
[[package]]
name = "zerovec-derive"
-version = "0.11.3"
+version = "0.11.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "625dc425cab0dca6dc3c3319506e6593dcb08a9f387ea3b284dbd52a92c40555"
+checksum = "34df6fc39dbd26ddc9c10e6a2984476e13acce22e64e4487636ef494369225da"
dependencies = [
"proc-macro2",
"quote",
- "syn 2.0.118",
+ "syn 3.0.6",
]
[[package]]
name = "zmij"
-version = "1.0.21"
+version = "1.0.23"
source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
diff --git a/Cargo.toml b/Cargo.toml
index 1289610..1b95f67 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,5 +1,5 @@
[workspace]
-members = ["crates/vcore-netstack"]
+members = ["crates/vcore-blake3-raw", "crates/vcore-netstack"]
resolver = "3"
[package]
@@ -23,6 +23,11 @@ name = "vcore-windows-session-host"
path = "src/bin/windows_session_host.rs"
required-features = ["ffi"]
+[[example]]
+name = "protocol-stream-probe"
+path = "tests/protocols/stream_probe.rs"
+required-features = ["interop-test", "stream-transport"]
+
[features]
default = [
"inbound-http",
@@ -30,14 +35,23 @@ default = [
"outbound-anytls",
"outbound-socks5",
"outbound-shadowsocks",
+ "outbound-trojan",
+ "outbound-vmess",
"outbound-vless",
+ "outbound-hysteria2",
]
inbound-http = []
inbound-socks5 = []
-outbound-anytls = ["dep:md-5"]
+outbound-anytls = ["dep:md-5", "tls-fingerprint"]
outbound-socks5 = []
outbound-shadowsocks = ["dep:shadowsocks", "dep:log"]
-outbound-vless = ["rustls/reality"]
+outbound-vless = ["tls-fingerprint", "boring/reality", "boring/jls", "boring/mlkem", "dep:blake3", "dep:hpke", "dep:zeroize", "dep:vcore-blake3-raw", "stream-transport", "quic-transport", "dep:hyper", "dep:hyper-util", "dep:h3", "dep:h3-quinn", "dep:yamux", "tokio-util/compat"]
+outbound-trojan = ["stream-transport", "tls-fingerprint"]
+outbound-vmess = ["stream-transport", "tls-fingerprint", "dep:aes", "dep:crc32fast", "dep:md-5", "dep:ring", "dep:shake"]
+tls-fingerprint = ["dep:boring", "dep:tokio-boring"]
+outbound-hysteria2 = ["quic-transport", "dep:quinn-proto", "dep:h3", "dep:h3-quinn", "dep:blake2"]
+stream-transport = ["dep:tokio-tungstenite", "dep:httparse", "dep:log"]
+quic-transport = ["dep:quinn"]
# Enables local interoperability-only trust-root injection. Release build
# scripts must not enable this feature.
interop-test = ["outbound-anytls", "outbound-vless"]
@@ -50,41 +64,64 @@ tun = [
"outbound-anytls",
"outbound-socks5",
"outbound-shadowsocks",
+ "outbound-trojan",
+ "outbound-vmess",
"outbound-vless",
+ "outbound-hysteria2",
]
[dependencies]
+aes = { version = "0.9.3", optional = true, features = ["zeroize"] }
arc-swap = "1"
async-trait = "0.1"
-base64 = "0.22"
+base64 = "0.23"
+blake2 = { version = "=0.11.0", optional = true }
+blake3 = { version = "=1.8.7", optional = true }
+boring = { git = "https://github.com/OneXray/boring", branch = "release", version = "=5.2.0", features = ["client-fingerprint"], optional = true }
bytes = "1"
-futures-util = "0.3"
-h2 = "0.4"
+crc32fast = { version = "1.5.2", optional = true }
+futures-util = { version = "0.3", features = ["sink"] }
+h2 = "0.4.19"
+h3 = { version = "=0.0.8", default-features = false, optional = true }
+h3-quinn = { version = "=0.0.10", default-features = false, optional = true }
+hpke = { version = "=0.14.1", default-features = false, features = ["alloc", "aes", "chacha", "x25519"], optional = true }
http = "1"
+hyper = { version = "=1.11.1", default-features = false, features = ["client", "http1"], optional = true }
+hyper-util = { version = "=0.1.20", default-features = false, features = ["tokio"], optional = true }
+httparse = { version = "1.10", optional = true }
idna = "1.1"
libc = "0.2"
# Upstream SS trace/debug logs include key material and traffic destinations.
# Keep the log facade compiled out when SS is linked; VCore uses tracing.
log = { version = "0.4", optional = true, features = ["max_level_off", "release_max_level_off"] }
-md-5 = { version = "0.10", optional = true }
-rand = "0.9"
+md-5 = { version = "0.11", optional = true }
+quinn = { version = "=0.11.12", default-features = false, features = ["runtime-tokio", "rustls-ring"], optional = true }
+quinn-proto = { version = "=0.11.18", default-features = false, features = ["rustls-ring"], optional = true }
+rand = "0.10"
+ring = { version = "0.17.14", optional = true }
regex-automata = { version = "0.4", default-features = false, features = ["dfa-build", "dfa-search", "syntax", "unicode"] }
-rustls = { version = "=0.23.43", default-features = false, features = ["ring", "std", "tls12"] }
+rustls = { version = "=0.23.45", default-features = false, features = ["ring", "std", "tls12"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
serde_yaml_ng = "0.10"
-sha2 = "0.10"
-shadowsocks = { git = "https://github.com/shadowsocks/shadowsocks-rust.git", rev = "ab388c7466d21f979430e33cc9ef10e22fb05955", optional = true, default-features = false, features = ["aead-cipher-2022"] }
+sha2 = "0.11"
+shake = { version = "0.1.0", optional = true }
+shadowsocks = { version = "=1.25.0", optional = true, default-features = false, features = ["aead-cipher-2022"] }
socket2 = { version = "0.6", features = ["all"] }
thiserror = "2"
tokio = { version = "1", features = ["io-util", "macros", "net", "rt", "sync", "time"] }
-tokio-rustls = { version = "=0.26.4", default-features = false, features = ["ring", "tls12"] }
+tokio-boring = { git = "https://github.com/OneXray/boring", branch = "release", version = "=5.2.0", optional = true }
+tokio-rustls = { version = "=0.26.5", default-features = false, features = ["ring", "tls12"] }
+tokio-tungstenite = { version = "=0.30.0", default-features = false, features = ["handshake"], optional = true }
tokio-util = { version = "0.7", features = ["rt"] }
tracing = "0.1"
url = "2"
uuid = { version = "1", features = ["serde"] }
vcore-netstack = { path = "crates/vcore-netstack", optional = true }
+vcore-blake3-raw = { path = "crates/vcore-blake3-raw", optional = true }
webpki-roots = "1"
+yamux = { version = "=0.14.1", optional = true }
+zeroize = { version = "=1.9.0", optional = true }
[target.'cfg(any(target_os = "ios", target_os = "macos"))'.dependencies]
oslog = { version = "0.2", default-features = false }
@@ -118,19 +155,22 @@ windows = { version = "=0.62.2", optional = true, features = [
"Win32_System_WinRT",
"Win32_UI_Shell",
] }
+# Keep the companion types required by the latest windows SDK. The separately
+# released 0.100.x crates are not type-compatible with windows 0.62.2.
windows-collections = { version = "=0.3.2", optional = true }
windows-core = { version = "=0.62.2", optional = true }
[dev-dependencies]
+# Native peer controls for bounded in-memory ALPS tests; same published fork.
+boring-sys = { git = "https://github.com/OneXray/boring", branch = "release", version = "=5.2.0" }
+foreign-types = "=0.5.0"
+tokio = { version = "1", features = ["test-util"] }
# Independent EIH relay fixture only; production crypto remains the official SS crate.
aes = "0.9"
blake3 = "1"
-rcgen = { version = "=0.14.8", default-features = false, features = ["crypto", "ring"] }
+rcgen = { version = "=0.14.10", default-features = false, features = ["crypto", "ring"] }
tempfile = "3"
-[patch.crates-io]
-rustls = { git = "https://github.com/OneVCore/rustls", branch = "vcore/reality-0.23" }
-
[profile.release]
codegen-units = 1
lto = "thin"
diff --git a/README.md b/README.md
index daa0b39..343b8ee 100644
--- a/README.md
+++ b/README.md
@@ -4,11 +4,11 @@
English · 简体中文 · Русский
-VCore is a standalone, host-agnostic Rust client proxy core. It provides proxy graphs, static `select` proxy groups, DNS, routing rules, GeoData, HTTP/SOCKS5 listeners, a TUN data plane, and a loopback Controller through strict YAML configuration and Invoke API v5. The internal configuration schema revision is 14; the revision appears only in the `version` response and `buildIdentity`, not in YAML.
+VCore is a standalone, host-agnostic Rust client proxy core. It provides proxy graphs, static `select` proxy groups, DNS, routing rules, GeoData, HTTP/SOCKS5 listeners, a TUN data plane, and a loopback Controller through strict YAML configuration and Invoke API v5. The internal configuration schema revision is 27; the revision appears only in the `version` response and `buildIdentity`, not in YAML.
## Features
-- Outbounds: VLESS + XHTTP + TLS/REALITY, SOCKS5 CONNECT/UDP ASSOCIATE, AnyTLS TCP/UoT, Shadowsocks 2022, and DIRECT. SS supports three standard 2022 algorithms and AES identity chains; see its [upstream risks and acceptance boundaries](docs/shadowsocks.md).
+- Outbounds: [VLESS TCP/WS/gRPC/HTTP/H2/XHTTP, TLS/REALITY and Vision](docs/vless.md), SOCKS5 CONNECT/UDP ASSOCIATE, AnyTLS TCP/UoT, Shadowsocks 2022, [Trojan TCP/UDP over TLS/WS/gRPC](docs/outbounds.md#trojan), [VMess AEAD over TCP/WS/gRPC/HTTP/H2](docs/outbounds.md#vmess-aead), [Hysteria2 TCP/UDP, bandwidth, Salamander and port hopping](docs/outbounds.md#hysteria2), and DIRECT. SS supports three standard 2022 algorithms and AES identity chains; see its [upstream risks and acceptance boundaries](docs/outbounds.md#shadowsocks-2022).
- Proxy chains: `dialer-proxy` forms a directed acyclic graph of arbitrary length. If node A points to B, the physical path is `client -> B -> A -> target`.
- Proxy groups: static `select` groups keep ordered members, including concrete nodes, nested groups, `DIRECT`, and `REJECT`; their current-session selection can be changed live through the Controller. `dialer-proxy` may reference nodes or groups; DIRECT in an upstream group connects the current node's prepared server.
- Routing: ordered `DOMAIN`, `DOMAIN-SUFFIX`, `DOMAIN-KEYWORD`, `GEOSITE`, `GEOIP`, `IP-CIDR`, `IP-CIDR6`, `DST-PORT`, `NETWORK`, and final `MATCH` rules.
@@ -17,6 +17,7 @@ VCore is a standalone, host-agnostic Rust client proxy core. It provides proxy g
- Listeners: HTTP CONNECT/forward with per-request authentication/routing, streaming bodies, Keep-Alive and Upgrade; SOCKS5 CONNECT and TCP-authorized UDP ASSOCIATE. Local access is unauthenticated by default; opt-in LAN sharing requires one shared username/password.
- GeoData: VCore manages `geosite.dat` and `geoip.dat` under `dataDir/geodata`, loads them on demand, and can update them through a proxy chain.
- Delay measurement: `measureDelay` accepts 1–5 node-only configurations per call, uses up to five private workers, and preserves input order in its results.
+- TLS: independent certificate pins and four opt-in ClientHello templates (Chrome120/133, Firefox120, Safari16.0) over TCP TLS/REALITY/JLS; see [public names, scope and limitations](docs/tls-client-fingerprint.md). [VLESS JLS](docs/vless.md#jls) uses separate shared credentials with complete native TLS authentication. [Static ECH](docs/vless.md#静态-ech) uses explicit VLESS main/download-leg configuration with no dynamic DNS lookup or fallback.
## Configuration
@@ -72,6 +73,8 @@ Authorization: Bearer
`GET /traffic` is a one-time `up/down/upTotal/downTotal` TUN snapshot. The group endpoints expose and change the selected direct member of static `select` groups; a successful change affects only new physical TCP, UDP, and DNS transports in the current session. It does not migrate existing connections, UDP associations, DNS state, or pooled TCP transports, and it never performs automatic failover. A Controller that manages groups requires one Bearer secret for all routes and may run without TUN. See [`docs/controller-api.md`](docs/controller-api.md).
+An authenticated Hysteria2 session keeps its upstream selection during port hopping. A replacement socket for that same QUIC session does not resample the group; only a new authenticated session does.
+
## Platforms
| Platform | Data plane | Status |
@@ -85,43 +88,15 @@ Windows does not use an fd emulation layer. The Provider owns only `VpnChannel`,
## Resource Bounds
-The current TUN profile keeps local structural bounds rather than a fixed admission limit on the total number of business flows:
-
-```text
-raw packet / MTU 1,500 bytes
-packet queue 256
-ordinary event / UDP response 128
-DNS ingress / DNS response 128 / 128
-TCP buffer 32 KiB per direction
-TLS / XHTTP buffer 64 KiB
-DNS typed cache 256 entries
-DNS opaque cache 64 entries / 256 KiB
-GeoData allocation capacity 8 MiB
-```
-
-Windows advertises a 1,400-byte L3 MTU as required by `StartWithMainTransport` and caps TUN UDP responses at 1,352 bytes; 1,500 bytes remain the cross-platform parser ceiling.
-
-TCP sessions, ordinary UDP associations, half-open connections, outbound handshakes, and active DNS transports are created on demand. Bounded queues, per-flow buffers, wire/parser limits, timeouts, idle cleanup, and caches provide structural safety. The iOS 35/45 MiB targets are best-effort observations and do not change lifecycle results.
+Safety is enforced through per-object queues, buffers, parser limits, deadlines and owned cancellation, not a global business-flow quota. See the [resource policy](docs/runtime-resource-policy.md) for shared limits and protocol-specific contracts for local budgets. Memory telemetry does not change lifecycle results.
## Documentation
- [Documentation index](docs/README.md)
-- [Configuration contract](docs/config.yaml)
+- [Configuration](docs/config.yaml)
- [Invoke API](docs/invoke-api.md)
-- [HTTP proxy inbound](docs/http-proxy.md)
-- [SOCKS5 proxy inbound](docs/socks5-proxy.md)
-- [AnyTLS outbound](docs/anytls.md)
-- [Shadowsocks 2022 outbound and limitations](docs/shadowsocks.md)
-- [REALITY V1 client protocol](docs/reality-wire-protocol.md)
-- [rustls REALITY dependency and release requirements](docs/rustls-reality-release.md)
-- [Runtime Controller](docs/controller-api.md)
-- [TUN ICMP and DNS](docs/tun-icmp-dns.md)
-- [GeoData rules and assets](docs/geodata.md)
-- [TUN platform layer](docs/tun-platform.md)
-- [Windows VPN platform boundary](docs/windows-vpn.md)
-- [Windows session runtime](docs/windows-session-runtime.md)
-- [Runtime resource policy](docs/runtime-resource-policy.md)
-- [Acceptance matrix](docs/acceptance.md)
+- [Build and test](scripts/README.md)
+- [Acceptance boundaries](docs/acceptance.md)
## Example
@@ -131,7 +106,7 @@ TCP sessions, ordinary UDP associations, half-open connections, outbound handsha
```bash
cargo fmt --all -- --check
-cargo test --all-features --all-targets
+uv run --project scripts --locked vcore-scripts check core --profile debug
cargo clippy --locked --all-features --lib --bins -- -D warnings
cargo test --manifest-path crates/vcore-netstack/Cargo.toml --all-targets
cargo clippy --manifest-path crates/vcore-netstack/Cargo.toml --all-targets -- -D warnings
@@ -159,7 +134,8 @@ VCore's dependencies, maintained forks, public API/protocol references, architec
- [smoltcp](https://github.com/smoltcp-rs/smoltcp), [clash-rs](https://github.com/Watfaq/clash-rs), and [netstack-smoltcp](https://github.com/automesh-network/netstack-smoltcp): userspace IP stacks and TUN netstacks.
- [windows-rs](https://github.com/microsoft/windows-rs), [UWP VPN Plugin Sample](https://github.com/microsoft/UwpVpnPluginSample), [wireguard-uwp-rs](https://github.com/luqmana/wireguard-uwp-rs), [Maple](https://github.com/YtFlow/Maple), and [YtFlowCore](https://github.com/YtFlow/YtFlowCore): Windows VPN, WinRT activation, and packet flow.
- [Xray-core](https://github.com/XTLS/Xray-core), [Mihomo](https://github.com/MetaCubeX/mihomo), and [Leaf](https://github.com/eycorsican/leaf): proxy protocols, routing, TUN architecture, and interoperability references.
-- [rustls](https://github.com/rustls/rustls): the TLS dependency and upstream of the maintained VCore REALITY fork.
+- [rustls](https://github.com/rustls/rustls): unprofiled TLS/QUIC and shared WebPKI certificate policy.
+- [boring](https://github.com/cloudflare/boring) and [BoringSSL](https://boringssl.googlesource.com/boringssl/): upstreams of the maintained fork for named ClientHello profiles and classic / opt-in hybrid REALITY.
- [shadowsocks-rust](https://github.com/shadowsocks/shadowsocks-rust): the unmodified SS 2022 protocol dependency and source of the derived UDP replay window; see the [MIT notices in the source header](src/outbound/shadowsocks/packet_window.rs).
## License
diff --git a/crates/vcore-blake3-raw/Cargo.toml b/crates/vcore-blake3-raw/Cargo.toml
new file mode 100644
index 0000000..2a22cd6
--- /dev/null
+++ b/crates/vcore-blake3-raw/Cargo.toml
@@ -0,0 +1,13 @@
+[package]
+name = "vcore-blake3-raw"
+version = "0.1.0"
+edition = "2024"
+license = "MIT"
+publish = false
+
+[build-dependencies]
+cc = "=1.5.1"
+
+[dev-dependencies]
+blake3 = "=1.8.7"
+serde_json = "1"
diff --git a/crates/vcore-blake3-raw/README.md b/crates/vcore-blake3-raw/README.md
new file mode 100644
index 0000000..0d69497
--- /dev/null
+++ b/crates/vcore-blake3-raw/README.md
@@ -0,0 +1,60 @@
+# Binary-context BLAKE3 DeriveKey
+
+Private workspace crate for the byte-string DeriveKey used on the VLESS
+Encryption wire. One public function accepts two byte slices and returns a
+32-byte key. It performs no allocation, IO, runtime loading, or TLS operation.
+Callers own input/output secrets and their erasure policy. The C adapter clears
+its hasher; it cannot guarantee erasure of upstream internal temporaries.
+
+The official Rust API takes `&str`; arbitrary binary protocol contexts cannot be
+converted to UTF-8, hex, or base64 without changing the derivation. The official
+C `blake3_hasher_init_derive_key_raw` is used directly. Rust does not mirror the
+C hasher layout or implement a compression/KDF algorithm.
+
+This reproduces an existing protocol, not a new cryptographic recommendation:
+BLAKE3's authors recommend a fixed, globally unique application-specific context,
+and caution against dynamic contexts. Compatibility does not establish the
+security of VLESS Encryption's protocol design.
+
+## Source and build
+
+The five `vendor/blake3*` files are byte-for-byte copies from official
+[BLAKE3 1.8.7](https://github.com/BLAKE3-team/BLAKE3/tree/1.8.7/c), commit
+`f3149ec5bb5449af877ba20377a11008ff499fa2` (latest stable checked 2026-09-26).
+Archive SHA-256: `c6782a28842b1c0478524ac06a4f2ede784038ee298d6e2162c0b089c4306a3c`.
+Upstream offers CC0-1.0, Apache-2.0, or Apache-2.0 WITH LLVM-exception; all three
+license texts are preserved in `vendor/`. Vendored source is used under
+Apache-2.0 WITH LLVM-exception. VCore-owned adapter/build/Rust code is MIT.
+
+| File | SHA-256 |
+| --- | --- |
+| blake3.c | b118ddf7cf9e6e5ef3fded72dcb1acf9dfdc4ea923cbe4605900ad6ee9afe1af |
+| blake3.h | 81bbb11ad1909341565dce4914cc0e5c29718eca27e6950b28f9226a91aaf8c5 |
+| blake3_impl.h | d388dca3574602c8849805ea3c8c0a12d082ac0e428756f305e111942f099af4 |
+| blake3_dispatch.c | 134f21550138c0af6312925c988aeee35df287e4119e8ad1d206fccdb2238fe3 |
+| blake3_portable.c | 2bc25b0dad67b4329d0b49cfa075ab2b0d04e424addbddc4e9c389c52a192524 |
+
+`build.rs` compiles these local files with official portable-only switches and
+compile-time symbol prefixes. It never accesses research checkouts, Cargo source
+caches, or the network. No bindgen, SIMD implementation, or fork is introduced.
+Latest stable `cc` 1.5.1 is selected explicitly. Upgrades require rechecking the
+official release, replacing unchanged files, updating provenance and hashes,
+and rerunning vectors and target builds.
+
+## Check
+
+```sh
+cargo test --locked -p vcore-blake3-raw
+```
+
+This checks a primitive, not the Encryption handshake, ticket authentication,
+runtime ownership, platform integration, or end-to-end Encryption acceptance.
+
+The binary-context fixture has 52 values generated with the independent
+`github.com/metacubex/blake3 v0.1.0` implementation used by Mihomo, using Go 1.27.1.
+Its SHA-256 is `16fa3198a0a6adad7de4df74010f1625b72a445991e8554842c0b12bd070b08d`.
+The generator and Go module lock are in `tests/generator/`; run `go run .` there
+to reproduce the JSON on stdout (not part of the Rust build). Inputs contain
+invalid UTF-8 and NUL and cover 64/1024-byte boundaries and protocol contexts up
+to 17005 bytes. UTF-8 cases also link and compare the official Rust crate in the
+same test executable.
diff --git a/crates/vcore-blake3-raw/build.rs b/crates/vcore-blake3-raw/build.rs
new file mode 100644
index 0000000..7646d0a
--- /dev/null
+++ b/crates/vcore-blake3-raw/build.rs
@@ -0,0 +1,46 @@
+fn main() {
+ let mut build = cc::Build::new();
+ build
+ .include("vendor")
+ .file("src/derive.c")
+ .file("vendor/blake3.c")
+ .file("vendor/blake3_dispatch.c")
+ .file("vendor/blake3_portable.c")
+ .std("c11")
+ .define("BLAKE3_NO_SSE2", None)
+ .define("BLAKE3_NO_SSE41", None)
+ .define("BLAKE3_NO_AVX2", None)
+ .define("BLAKE3_NO_AVX512", None)
+ .define("BLAKE3_USE_NEON", "0")
+ .define("BLAKE3_API", "")
+ .define("BLAKE3_PRIVATE", "")
+ .flag_if_supported("-fvisibility=hidden");
+
+ // Prefix at compilation, never by modifying the vendored official source.
+ // The regular Rust blake3 crate can link into the same final executable.
+ for symbol in [
+ "blake3_version",
+ "blake3_hasher_init",
+ "blake3_hasher_init_keyed",
+ "blake3_hasher_init_derive_key",
+ "blake3_hasher_init_derive_key_raw",
+ "blake3_hasher_update",
+ "blake3_hasher_finalize",
+ "blake3_hasher_finalize_seek",
+ "blake3_hasher_reset",
+ "blake3_compress_subtree_wide",
+ "blake3_compress_in_place",
+ "blake3_compress_xof",
+ "blake3_xof_many",
+ "blake3_hash_many",
+ "blake3_simd_degree",
+ "blake3_compress_in_place_portable",
+ "blake3_compress_xof_portable",
+ "blake3_hash_many_portable",
+ ] {
+ build.define(symbol, format!("vcore_raw_{symbol}").as_str());
+ }
+ build.compile("vcore_blake3_raw");
+ println!("cargo:rerun-if-changed=src/derive.c");
+ println!("cargo:rerun-if-changed=vendor");
+}
diff --git a/crates/vcore-blake3-raw/src/derive.c b/crates/vcore-blake3-raw/src/derive.c
new file mode 100644
index 0000000..36293b0
--- /dev/null
+++ b/crates/vcore-blake3-raw/src/derive.c
@@ -0,0 +1,18 @@
+/* VCore-owned one-shot adapter. The BLAKE3 implementation is unmodified. */
+#include "blake3.h"
+
+void vcore_blake3_raw_derive(const unsigned char *context, size_t context_len,
+ const unsigned char *material, size_t material_len,
+ unsigned char output[32]) {
+ blake3_hasher hasher;
+ blake3_hasher_init_derive_key_raw(&hasher, context, context_len);
+ blake3_hasher_update(&hasher, material, material_len);
+ blake3_hasher_finalize(&hasher, output, 32);
+
+ /* Erase this adapter's state without optimizing the stores away. This does
+ not promise erasure of temporaries inside the unmodified upstream code. */
+ volatile unsigned char *state = (volatile unsigned char *)&hasher;
+ for (size_t i = 0; i < sizeof(hasher); ++i) {
+ state[i] = 0;
+ }
+}
diff --git a/crates/vcore-blake3-raw/src/lib.rs b/crates/vcore-blake3-raw/src/lib.rs
new file mode 100644
index 0000000..71eb498
--- /dev/null
+++ b/crates/vcore-blake3-raw/src/lib.rs
@@ -0,0 +1,31 @@
+//! One-shot BLAKE3 key derivation with a byte-string context.
+
+/// Derive a 32-byte key, preserving every byte of the context and key material.
+///
+/// The caller owns the returned secret and is responsible for erasing it.
+pub fn derive_key(context: &[u8], key_material: &[u8]) -> [u8; 32] {
+ let mut output = [0; 32];
+ // SAFETY: both input pointers are valid for their supplied slice lengths,
+ // including empty slices. The disjoint output holds exactly 32 bytes. The
+ // synchronous C wrapper retains no pointers and exposes no private layout.
+ unsafe {
+ vcore_blake3_raw_derive(
+ context.as_ptr(),
+ context.len(),
+ key_material.as_ptr(),
+ key_material.len(),
+ output.as_mut_ptr(),
+ );
+ }
+ output
+}
+
+unsafe extern "C" {
+ fn vcore_blake3_raw_derive(
+ context: *const u8,
+ context_len: usize,
+ material: *const u8,
+ material_len: usize,
+ output: *mut u8,
+ );
+}
diff --git a/crates/vcore-blake3-raw/tests/derive.rs b/crates/vcore-blake3-raw/tests/derive.rs
new file mode 100644
index 0000000..1e897ae
--- /dev/null
+++ b/crates/vcore-blake3-raw/tests/derive.rs
@@ -0,0 +1,52 @@
+use vcore_blake3_raw::derive_key;
+
+#[test]
+fn derives_binary_context_without_utf8_conversion() {
+ // Independent github.com/metacubex/blake3 v0.1.0 DeriveKey result.
+ let context: Vec = (0..16).map(|i| (i * 37 + 255) as u8).collect();
+ let material: Vec = (0..32).map(|i| (i * 13 + 7) as u8).collect();
+ let actual: String = derive_key(&context, &material)
+ .iter()
+ .map(|b| format!("{b:02x}"))
+ .collect();
+ assert_eq!(
+ actual,
+ "853b1d12dc08c5f34a282e668cc51fa4e34a5213ecd9d036773696493d6a19ba"
+ );
+}
+
+#[test]
+fn matches_independent_go_vectors_across_block_chunk_and_wire_context_lengths() {
+ let fixtures: serde_json::Value =
+ serde_json::from_str(include_str!("fixtures/blake3-binary-context-vectors.json")).unwrap();
+ let vectors = fixtures["vectors"].as_array().unwrap();
+ assert_eq!(vectors.len(), 52);
+ for vector in vectors {
+ let context_len = vector["context_length"].as_u64().unwrap() as usize;
+ let key_len = vector["key_length"].as_u64().unwrap() as usize;
+ let context: Vec = (0..context_len).map(|i| (i * 37 + 255) as u8).collect();
+ let material: Vec = (0..key_len).map(|i| (i * 13 + 7) as u8).collect();
+ let actual: String = derive_key(&context, &material)
+ .iter()
+ .map(|b| format!("{b:02x}"))
+ .collect();
+ assert_eq!(
+ actual,
+ vector["output"].as_str().unwrap(),
+ "context={context_len}, material={key_len}"
+ );
+ }
+}
+
+#[test]
+fn coexists_with_official_rust_blake3_and_matches_its_utf8_interface() {
+ for context in ["", "VLESS", "vcore tests 2026-09-26 固定 context\0with NUL"] {
+ for length in [0, 1, 32, 64, 1023, 1024, 1025, 17005] {
+ let material: Vec = (0..length).map(|i| (i * 13 + 7) as u8).collect();
+ assert_eq!(
+ derive_key(context.as_bytes(), &material),
+ blake3::derive_key(context, &material)
+ );
+ }
+ }
+}
diff --git a/crates/vcore-blake3-raw/tests/fixtures/blake3-binary-context-vectors.json b/crates/vcore-blake3-raw/tests/fixtures/blake3-binary-context-vectors.json
new file mode 100644
index 0000000..499eb2a
--- /dev/null
+++ b/crates/vcore-blake3-raw/tests/fixtures/blake3-binary-context-vectors.json
@@ -0,0 +1,268 @@
+{
+ "context_pattern": "byte(i*37 + 255)",
+ "generator": "github.com/metacubex/blake3@v0.1.0",
+ "go_version": "go1.27.1",
+ "key_pattern": "byte(i*13 + 7)",
+ "vectors": [
+ {
+ "context_length": 0,
+ "key_length": 0,
+ "output": "741011989511e0d6b52532320d9edb6c0def0ab7e832b99bcc1259591ce2d75b"
+ },
+ {
+ "context_length": 0,
+ "key_length": 32,
+ "output": "5c3d866c66aa5509a24a982595396810c0f8d2eb8cfd50fd376f49ddc80d74cd"
+ },
+ {
+ "context_length": 0,
+ "key_length": 64,
+ "output": "28e7a122e4ae1fd45d84bde76961352d9fe0946fb3190405df7f8e0902a9da04"
+ },
+ {
+ "context_length": 0,
+ "key_length": 96,
+ "output": "282dbfb0b9b7ecee8f86740fc47cb43bfc9e7b19673646b5eeaa6706866d0e89"
+ },
+ {
+ "context_length": 1,
+ "key_length": 0,
+ "output": "d53da9fb267add567423b045a78090195b8d2d8384a413d7a40b2af02b081b3c"
+ },
+ {
+ "context_length": 1,
+ "key_length": 32,
+ "output": "a1697a1da3f18b4fe54a92c8c9209bc619b991a2c8da37d544d2698df8672498"
+ },
+ {
+ "context_length": 1,
+ "key_length": 64,
+ "output": "83dbd99441ad83e40c503cf0350d7445b259afc9cb081fc4f51a623fd19f177f"
+ },
+ {
+ "context_length": 1,
+ "key_length": 96,
+ "output": "a7621a490de87ec7d68b1a272d46b65a449cb031af76d534b0213b1780af0135"
+ },
+ {
+ "context_length": 16,
+ "key_length": 0,
+ "output": "8ec56afd22a625be532f37efd05aa12fa45b4f35ad07a5662eb6915781e7972a"
+ },
+ {
+ "context_length": 16,
+ "key_length": 32,
+ "output": "853b1d12dc08c5f34a282e668cc51fa4e34a5213ecd9d036773696493d6a19ba"
+ },
+ {
+ "context_length": 16,
+ "key_length": 64,
+ "output": "b974c88487ab05f48b43edbb6dad8688a0422d96bd2a88d72b5fb55e17fc3ae3"
+ },
+ {
+ "context_length": 16,
+ "key_length": 96,
+ "output": "1bb66bda20f8e51ca3ded31fe6d027aa14d2aff6810545eca7a65356cf095dbe"
+ },
+ {
+ "context_length": 32,
+ "key_length": 0,
+ "output": "ac50ff84429785daf1388fdc74d85eec7ca1c5a4759f1e729138856394139d87"
+ },
+ {
+ "context_length": 32,
+ "key_length": 32,
+ "output": "868cad5faa4b6a36f8d93655679392d72e4bfb5cae341574ac2a8620c6a3fc68"
+ },
+ {
+ "context_length": 32,
+ "key_length": 64,
+ "output": "d908d23c6a10f8c5b75decd181728bc55d758d0b2c9faa4c58178752736cc4ba"
+ },
+ {
+ "context_length": 32,
+ "key_length": 96,
+ "output": "b22e9062a43df3713be845ac69322df62b1b44c0013e016a96065f4890d92e1a"
+ },
+ {
+ "context_length": 63,
+ "key_length": 0,
+ "output": "e5171a92930fcf36afdbf7d6361d998103434eb5cf5eab80ac775f2dff90d9f0"
+ },
+ {
+ "context_length": 63,
+ "key_length": 32,
+ "output": "2ab26669ae07bb11a23da55b635ef48bcf000509cacb19e1a2d474f9e37af167"
+ },
+ {
+ "context_length": 63,
+ "key_length": 64,
+ "output": "79e7e69f2926ac044fe860f119cef33d6395204b6f743ca49a1eecdb2da30829"
+ },
+ {
+ "context_length": 63,
+ "key_length": 96,
+ "output": "de7eeeaa212a6bcbe3cb623120500ad4ded3d6d1888637ea46922259e8d9b969"
+ },
+ {
+ "context_length": 64,
+ "key_length": 0,
+ "output": "a018e9df76b09153906cb5f66a0111c08c6ac6691f12071a21f4243ae37a4b1b"
+ },
+ {
+ "context_length": 64,
+ "key_length": 32,
+ "output": "f88c72bc16d746fa394241112415ccd035f2475d888e8c9208d7bf9c20272956"
+ },
+ {
+ "context_length": 64,
+ "key_length": 64,
+ "output": "9154d9ef3d611d28d7d35c9c387c87db8db9bf024c595f1d63749f6a434f9bf7"
+ },
+ {
+ "context_length": 64,
+ "key_length": 96,
+ "output": "7b937eed3f5c5b5f01c1990b14ddacca052151b759d8da864beaa9521e74bc9b"
+ },
+ {
+ "context_length": 65,
+ "key_length": 0,
+ "output": "c1b475b71a2fdf3d334108dbf8ea8e40f2a0d18216cbb1a24da9e8551acfb74e"
+ },
+ {
+ "context_length": 65,
+ "key_length": 32,
+ "output": "c5effde6b388307a3f5c58c9cb4fe7883c1293b8ef5e238a05828ae7ffb14002"
+ },
+ {
+ "context_length": 65,
+ "key_length": 64,
+ "output": "f7e06704e58d53ea0738a2fb4021f6c5ba4b5506c132c8d50b7cf73439361717"
+ },
+ {
+ "context_length": 65,
+ "key_length": 96,
+ "output": "48f7b450e72b23540fe485581793762439f22d328fe7b52eb2911391477b5513"
+ },
+ {
+ "context_length": 1023,
+ "key_length": 0,
+ "output": "ae51881daa67fff0ca9caaed5a4ab4c5664ffbe95fc9195047e78c3344c799e0"
+ },
+ {
+ "context_length": 1023,
+ "key_length": 32,
+ "output": "1493d5c97eaac5df219395f5e59b1c66d163a88ed975d21757a57057a623d5e2"
+ },
+ {
+ "context_length": 1023,
+ "key_length": 64,
+ "output": "3ae30f3112bca1a4c839098c331518576589161212e17a517575a1aedfd052f2"
+ },
+ {
+ "context_length": 1023,
+ "key_length": 96,
+ "output": "3b37a481bb95dc116c870338d8702ea03203ad7b7be125063854cd33ffbfec06"
+ },
+ {
+ "context_length": 1024,
+ "key_length": 0,
+ "output": "d55f97eceb7dc4ce43fccbbd56977b851e68fb34f2c9968141ef1e4479d1c021"
+ },
+ {
+ "context_length": 1024,
+ "key_length": 32,
+ "output": "bba6b1461919e559cfca385931d8e6e395abad848951345abed2d72ac3ea6b9d"
+ },
+ {
+ "context_length": 1024,
+ "key_length": 64,
+ "output": "362eef17ded94eb6a8b92ae23c358a55d090369e61265ccc84a087614923d211"
+ },
+ {
+ "context_length": 1024,
+ "key_length": 96,
+ "output": "04eb7f933497554b7539091ab3c157ea3f8dac1c683a1a800a69527dc33d80a4"
+ },
+ {
+ "context_length": 1025,
+ "key_length": 0,
+ "output": "bf8a4c338519e453f673aa3069df1c600ebb02d8965e98d59c38734d0cbb52fe"
+ },
+ {
+ "context_length": 1025,
+ "key_length": 32,
+ "output": "c7328a6379382cd5cd6b124595226a49e80562098b394c846d8286ebc42b4316"
+ },
+ {
+ "context_length": 1025,
+ "key_length": 64,
+ "output": "c2c3d7c40d077227bef58629709223ae0871aee18d28292b1484b9ae55ef9f18"
+ },
+ {
+ "context_length": 1025,
+ "key_length": 96,
+ "output": "0b426d2a0cdc93d867a3c31649db4e5464c25a7ec15d7fdb47c743f377310626"
+ },
+ {
+ "context_length": 1120,
+ "key_length": 0,
+ "output": "09c90c6e5021e06227b22bcd9cff06c78c143e215d209c347f05071322d9d206"
+ },
+ {
+ "context_length": 1120,
+ "key_length": 32,
+ "output": "cfd9bf5c7d60830d6ed7a122c0b0c93e98c5fe902c06cdea604a256d62b3741d"
+ },
+ {
+ "context_length": 1120,
+ "key_length": 64,
+ "output": "8283905b141b0000e38a46b0b550402cd8f134a815729a85a5d1f568daa07cbc"
+ },
+ {
+ "context_length": 1120,
+ "key_length": 96,
+ "output": "e991d2062bd9ee1940b40e4a48078ab9a4aee7bd732eb36ea8890f48b567a873"
+ },
+ {
+ "context_length": 1216,
+ "key_length": 0,
+ "output": "5cc36e83e6b8b78f623e3058aa18590d16ac8b9f7a0967da26ba2ba7bc1a0c39"
+ },
+ {
+ "context_length": 1216,
+ "key_length": 32,
+ "output": "4b7ca04d45003d06a1930c5a564c0445337a0a615a656842c5614fdf9105d70f"
+ },
+ {
+ "context_length": 1216,
+ "key_length": 64,
+ "output": "19fb3137b53173539090def86175e5ac2770a80e7adf761bde3d0ad4c81ec0f1"
+ },
+ {
+ "context_length": 1216,
+ "key_length": 96,
+ "output": "78229c88df99a2af3399a2451a2354da3ef0e424ee769867fe9d8f3b48d4ebb5"
+ },
+ {
+ "context_length": 17005,
+ "key_length": 0,
+ "output": "4625bc3910fe2dcb10416934b654cfcc6ea1e36aa7237aa778e28a9fc202e222"
+ },
+ {
+ "context_length": 17005,
+ "key_length": 32,
+ "output": "a5ed129744ad5b6fe17ea7483894ff6c33222a31137598b670eab451e3ad3c08"
+ },
+ {
+ "context_length": 17005,
+ "key_length": 64,
+ "output": "6df4a7125f4546428469b09aae90733ec9d2bfc0330b7d9b18375bdf4f5683e5"
+ },
+ {
+ "context_length": 17005,
+ "key_length": 96,
+ "output": "25b9781600c2f8040c4f55515fb9a40d1c473f613df2df5e8379233ed4804685"
+ }
+ ]
+}
diff --git a/crates/vcore-blake3-raw/tests/generator/go.mod b/crates/vcore-blake3-raw/tests/generator/go.mod
new file mode 100644
index 0000000..3b4fb16
--- /dev/null
+++ b/crates/vcore-blake3-raw/tests/generator/go.mod
@@ -0,0 +1,7 @@
+module vcore-blake3-vectors
+
+go 1.27.0
+
+require github.com/metacubex/blake3 v0.1.0
+
+require golang.org/x/sys v0.48.0 // indirect
diff --git a/crates/vcore-blake3-raw/tests/generator/go.sum b/crates/vcore-blake3-raw/tests/generator/go.sum
new file mode 100644
index 0000000..e636975
--- /dev/null
+++ b/crates/vcore-blake3-raw/tests/generator/go.sum
@@ -0,0 +1,6 @@
+github.com/metacubex/blake3 v0.1.0 h1:KGnjh/56REO7U+cgZA8dnBhxdP7jByrG7hTP+bu6cqY=
+github.com/metacubex/blake3 v0.1.0/go.mod h1:CCkLdzFrqf7xmxCdhQFvJsRRV2mwOLDoSPg6vUTB9Uk=
+golang.org/x/sys v0.30.0 h1:QjkSwP/36a20jFYWkSue1YwXzLmsV5Gfq7Eiy72C1uc=
+golang.org/x/sys v0.30.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/sys v0.48.0 h1:bbX/i/6MgT9BVLM9RT1thmxL04yeTAhbEz4SyadbXoo=
+golang.org/x/sys v0.48.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og=
diff --git a/crates/vcore-blake3-raw/tests/generator/main.go b/crates/vcore-blake3-raw/tests/generator/main.go
new file mode 100644
index 0000000..4d47e3d
--- /dev/null
+++ b/crates/vcore-blake3-raw/tests/generator/main.go
@@ -0,0 +1,46 @@
+// Independent wire-compatibility vectors; no network listeners or protocol engine.
+package main
+
+import (
+ "encoding/hex"
+ "encoding/json"
+ "os"
+ "runtime"
+
+ "github.com/metacubex/blake3"
+)
+
+func pattern(length, step, start int) []byte {
+ out := make([]byte, length)
+ for i := range out {
+ out[i] = byte(i*step + start)
+ }
+ return out
+}
+
+func main() {
+ type vector struct {
+ ContextLength int `json:"context_length"`
+ KeyLength int `json:"key_length"`
+ Output string `json:"output"`
+ }
+ var vectors []vector
+ for _, contextLength := range []int{0, 1, 16, 32, 63, 64, 65, 1023, 1024, 1025, 1120, 1216, 17005} {
+ for _, keyLength := range []int{0, 32, 64, 96} {
+ out := make([]byte, 32)
+ blake3.DeriveKey(out, string(pattern(contextLength, 37, 255)), pattern(keyLength, 13, 7))
+ vectors = append(vectors, vector{contextLength, keyLength, hex.EncodeToString(out)})
+ }
+ }
+ encoder := json.NewEncoder(os.Stdout)
+ encoder.SetIndent("", " ")
+ if err := encoder.Encode(map[string]any{
+ "generator": "github.com/metacubex/blake3@v0.1.0",
+ "go_version": runtime.Version(),
+ "context_pattern": "byte(i*37 + 255)",
+ "key_pattern": "byte(i*13 + 7)",
+ "vectors": vectors,
+ }); err != nil {
+ panic(err)
+ }
+}
diff --git a/crates/vcore-blake3-raw/vendor/.gitattributes b/crates/vcore-blake3-raw/vendor/.gitattributes
new file mode 100644
index 0000000..9852d38
--- /dev/null
+++ b/crates/vcore-blake3-raw/vendor/.gitattributes
@@ -0,0 +1,3 @@
+# Preserve the official release bytes, including upstream whitespace.
+blake3_impl.h whitespace=-blank-at-eol
+LICENSE_A2LLVM whitespace=-blank-at-eof
diff --git a/crates/vcore-blake3-raw/vendor/LICENSE_A2 b/crates/vcore-blake3-raw/vendor/LICENSE_A2
new file mode 100644
index 0000000..d512ca9
--- /dev/null
+++ b/crates/vcore-blake3-raw/vendor/LICENSE_A2
@@ -0,0 +1,202 @@
+
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright 2019 Jack O'Connor and Samuel Neves
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
diff --git a/crates/vcore-blake3-raw/vendor/LICENSE_A2LLVM b/crates/vcore-blake3-raw/vendor/LICENSE_A2LLVM
new file mode 100644
index 0000000..8d11bec
--- /dev/null
+++ b/crates/vcore-blake3-raw/vendor/LICENSE_A2LLVM
@@ -0,0 +1,219 @@
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright 2019 Jack O'Connor and Samuel Neves
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+
+---- LLVM Exceptions to the Apache 2.0 License ----
+
+As an exception, if, as a result of your compiling your source code, portions
+of this Software are embedded into an Object form of such source code, you
+may redistribute such embedded portions in such Object form without complying
+with the conditions of Sections 4(a), 4(b) and 4(d) of the License.
+
+In addition, if you combine or link compiled forms of this Software with
+software that is licensed under the GPLv2 ("Combined Software") and if a
+court of competent jurisdiction determines that the patent provision (Section
+3), the indemnity provision (Section 9) or other Section of the License
+conflicts with the conditions of the GPLv2, you may retroactively and
+prospectively choose to deem waived or otherwise exclude such Section(s) of
+the License, but only in their entirety and only with respect to the Combined
+Software.
+
diff --git a/crates/vcore-blake3-raw/vendor/LICENSE_CC0 b/crates/vcore-blake3-raw/vendor/LICENSE_CC0
new file mode 100644
index 0000000..0e259d4
--- /dev/null
+++ b/crates/vcore-blake3-raw/vendor/LICENSE_CC0
@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+ CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+ LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+ ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+ INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+ REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+ PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+ THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+ HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+ i. the right to reproduce, adapt, distribute, perform, display,
+ communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+ likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+ subject to the limitations in paragraph 4(a), below;
+ v. rights protecting the extraction, dissemination, use and reuse of data
+ in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+ European Parliament and of the Council of 11 March 1996 on the legal
+ protection of databases, and under any national implementation
+ thereof, including any amended or successor version of such
+ directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+ world based on applicable law or treaty, and any national
+ implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+ surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+ warranties of any kind concerning the Work, express, implied,
+ statutory or otherwise, including without limitation warranties of
+ title, merchantability, fitness for a particular purpose, non
+ infringement, or the absence of latent or other defects, accuracy, or
+ the present or absence of errors, whether or not discoverable, all to
+ the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+ that may apply to the Work or any use thereof, including without
+ limitation any person's Copyright and Related Rights in the Work.
+ Further, Affirmer disclaims responsibility for obtaining any necessary
+ consents, permissions or other rights required for any use of the
+ Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+ party to this document and has no duty or obligation with respect to
+ this CC0 or use of the Work.
diff --git a/crates/vcore-blake3-raw/vendor/blake3.c b/crates/vcore-blake3-raw/vendor/blake3.c
new file mode 100644
index 0000000..00f91f4
--- /dev/null
+++ b/crates/vcore-blake3-raw/vendor/blake3.c
@@ -0,0 +1,651 @@
+#include
+#include
+#include
+#include
+
+#include "blake3.h"
+#include "blake3_impl.h"
+
+const char *blake3_version(void) { return BLAKE3_VERSION_STRING; }
+
+INLINE void chunk_state_init(blake3_chunk_state *self, const uint32_t key[8],
+ uint8_t flags) {
+ memcpy(self->cv, key, BLAKE3_KEY_LEN);
+ self->chunk_counter = 0;
+ memset(self->buf, 0, BLAKE3_BLOCK_LEN);
+ self->buf_len = 0;
+ self->blocks_compressed = 0;
+ self->flags = flags;
+}
+
+INLINE void chunk_state_reset(blake3_chunk_state *self, const uint32_t key[8],
+ uint64_t chunk_counter) {
+ memcpy(self->cv, key, BLAKE3_KEY_LEN);
+ self->chunk_counter = chunk_counter;
+ self->blocks_compressed = 0;
+ memset(self->buf, 0, BLAKE3_BLOCK_LEN);
+ self->buf_len = 0;
+}
+
+INLINE size_t chunk_state_len(const blake3_chunk_state *self) {
+ return (BLAKE3_BLOCK_LEN * (size_t)self->blocks_compressed) +
+ ((size_t)self->buf_len);
+}
+
+INLINE size_t chunk_state_fill_buf(blake3_chunk_state *self,
+ const uint8_t *input, size_t input_len) {
+ size_t take = BLAKE3_BLOCK_LEN - ((size_t)self->buf_len);
+ if (take > input_len) {
+ take = input_len;
+ }
+ uint8_t *dest = self->buf + ((size_t)self->buf_len);
+ memcpy(dest, input, take);
+ self->buf_len += (uint8_t)take;
+ return take;
+}
+
+INLINE uint8_t chunk_state_maybe_start_flag(const blake3_chunk_state *self) {
+ if (self->blocks_compressed == 0) {
+ return CHUNK_START;
+ } else {
+ return 0;
+ }
+}
+
+typedef struct {
+ uint32_t input_cv[8];
+ uint64_t counter;
+ uint8_t block[BLAKE3_BLOCK_LEN];
+ uint8_t block_len;
+ uint8_t flags;
+} output_t;
+
+INLINE output_t make_output(const uint32_t input_cv[8],
+ const uint8_t block[BLAKE3_BLOCK_LEN],
+ uint8_t block_len, uint64_t counter,
+ uint8_t flags) {
+ output_t ret;
+ memcpy(ret.input_cv, input_cv, 32);
+ memcpy(ret.block, block, BLAKE3_BLOCK_LEN);
+ ret.block_len = block_len;
+ ret.counter = counter;
+ ret.flags = flags;
+ return ret;
+}
+
+// Chaining values within a given chunk (specifically the compress_in_place
+// interface) are represented as words. This avoids unnecessary bytes<->words
+// conversion overhead in the portable implementation. However, the hash_many
+// interface handles both user input and parent node blocks, so it accepts
+// bytes. For that reason, chaining values in the CV stack are represented as
+// bytes.
+INLINE void output_chaining_value(const output_t *self, uint8_t cv[32]) {
+ uint32_t cv_words[8];
+ memcpy(cv_words, self->input_cv, 32);
+ blake3_compress_in_place(cv_words, self->block, self->block_len,
+ self->counter, self->flags);
+ store_cv_words(cv, cv_words);
+}
+
+INLINE void output_root_bytes(const output_t *self, uint64_t seek, uint8_t *out,
+ size_t out_len) {
+ if (out_len == 0) {
+ return;
+ }
+ uint64_t output_block_counter = seek / 64;
+ size_t offset_within_block = seek % 64;
+ uint8_t wide_buf[64];
+ if(offset_within_block) {
+ blake3_compress_xof(self->input_cv, self->block, self->block_len, output_block_counter, self->flags | ROOT, wide_buf);
+ const size_t available_bytes = 64 - offset_within_block;
+ const size_t bytes = out_len > available_bytes ? available_bytes : out_len;
+ memcpy(out, wide_buf + offset_within_block, bytes);
+ out += bytes;
+ out_len -= bytes;
+ output_block_counter += 1;
+ }
+ if(out_len / 64) {
+ blake3_xof_many(self->input_cv, self->block, self->block_len, output_block_counter, self->flags | ROOT, out, out_len / 64);
+ }
+ output_block_counter += out_len / 64;
+ out += out_len & -64;
+ out_len -= out_len & -64;
+ if(out_len) {
+ blake3_compress_xof(self->input_cv, self->block, self->block_len, output_block_counter, self->flags | ROOT, wide_buf);
+ memcpy(out, wide_buf, out_len);
+ }
+}
+
+INLINE void chunk_state_update(blake3_chunk_state *self, const uint8_t *input,
+ size_t input_len) {
+ if (self->buf_len > 0) {
+ size_t take = chunk_state_fill_buf(self, input, input_len);
+ input += take;
+ input_len -= take;
+ if (input_len > 0) {
+ blake3_compress_in_place(
+ self->cv, self->buf, BLAKE3_BLOCK_LEN, self->chunk_counter,
+ self->flags | chunk_state_maybe_start_flag(self));
+ self->blocks_compressed += 1;
+ self->buf_len = 0;
+ memset(self->buf, 0, BLAKE3_BLOCK_LEN);
+ }
+ }
+
+ while (input_len > BLAKE3_BLOCK_LEN) {
+ blake3_compress_in_place(self->cv, input, BLAKE3_BLOCK_LEN,
+ self->chunk_counter,
+ self->flags | chunk_state_maybe_start_flag(self));
+ self->blocks_compressed += 1;
+ input += BLAKE3_BLOCK_LEN;
+ input_len -= BLAKE3_BLOCK_LEN;
+ }
+
+ chunk_state_fill_buf(self, input, input_len);
+}
+
+INLINE output_t chunk_state_output(const blake3_chunk_state *self) {
+ uint8_t block_flags =
+ self->flags | chunk_state_maybe_start_flag(self) | CHUNK_END;
+ return make_output(self->cv, self->buf, self->buf_len, self->chunk_counter,
+ block_flags);
+}
+
+INLINE output_t parent_output(const uint8_t block[BLAKE3_BLOCK_LEN],
+ const uint32_t key[8], uint8_t flags) {
+ return make_output(key, block, BLAKE3_BLOCK_LEN, 0, flags | PARENT);
+}
+
+// Given some input larger than one chunk, return the number of bytes that
+// should go in the left subtree. This is the largest power-of-2 number of
+// chunks that leaves at least 1 byte for the right subtree.
+INLINE size_t left_subtree_len(size_t input_len) {
+ // Subtract 1 to reserve at least one byte for the right side. input_len
+ // should always be greater than BLAKE3_CHUNK_LEN.
+ size_t full_chunks = (input_len - 1) / BLAKE3_CHUNK_LEN;
+ return round_down_to_power_of_2(full_chunks) * BLAKE3_CHUNK_LEN;
+}
+
+// Use SIMD parallelism to hash up to MAX_SIMD_DEGREE chunks at the same time
+// on a single thread. Write out the chunk chaining values and return the
+// number of chunks hashed. These chunks are never the root and never empty;
+// those cases use a different codepath.
+INLINE size_t compress_chunks_parallel(const uint8_t *input, size_t input_len,
+ const uint32_t key[8],
+ uint64_t chunk_counter, uint8_t flags,
+ uint8_t *out) {
+#if defined(BLAKE3_TESTING)
+ assert(0 < input_len);
+ assert(input_len <= MAX_SIMD_DEGREE * BLAKE3_CHUNK_LEN);
+#endif
+
+ const uint8_t *chunks_array[MAX_SIMD_DEGREE];
+ size_t input_position = 0;
+ size_t chunks_array_len = 0;
+ while (input_len - input_position >= BLAKE3_CHUNK_LEN) {
+ chunks_array[chunks_array_len] = &input[input_position];
+ input_position += BLAKE3_CHUNK_LEN;
+ chunks_array_len += 1;
+ }
+
+ blake3_hash_many(chunks_array, chunks_array_len,
+ BLAKE3_CHUNK_LEN / BLAKE3_BLOCK_LEN, key, chunk_counter,
+ true, flags, CHUNK_START, CHUNK_END, out);
+
+ // Hash the remaining partial chunk, if there is one. Note that the empty
+ // chunk (meaning the empty message) is a different codepath.
+ if (input_len > input_position) {
+ uint64_t counter = chunk_counter + (uint64_t)chunks_array_len;
+ blake3_chunk_state chunk_state;
+ chunk_state_init(&chunk_state, key, flags);
+ chunk_state.chunk_counter = counter;
+ chunk_state_update(&chunk_state, &input[input_position],
+ input_len - input_position);
+ output_t output = chunk_state_output(&chunk_state);
+ output_chaining_value(&output, &out[chunks_array_len * BLAKE3_OUT_LEN]);
+ return chunks_array_len + 1;
+ } else {
+ return chunks_array_len;
+ }
+}
+
+// Use SIMD parallelism to hash up to MAX_SIMD_DEGREE parents at the same time
+// on a single thread. Write out the parent chaining values and return the
+// number of parents hashed. (If there's an odd input chaining value left over,
+// return it as an additional output.) These parents are never the root and
+// never empty; those cases use a different codepath.
+INLINE size_t compress_parents_parallel(const uint8_t *child_chaining_values,
+ size_t num_chaining_values,
+ const uint32_t key[8], uint8_t flags,
+ uint8_t *out) {
+#if defined(BLAKE3_TESTING)
+ assert(2 <= num_chaining_values);
+ assert(num_chaining_values <= 2 * MAX_SIMD_DEGREE_OR_2);
+#endif
+
+ const uint8_t *parents_array[MAX_SIMD_DEGREE_OR_2];
+ size_t parents_array_len = 0;
+ while (num_chaining_values - (2 * parents_array_len) >= 2) {
+ parents_array[parents_array_len] =
+ &child_chaining_values[2 * parents_array_len * BLAKE3_OUT_LEN];
+ parents_array_len += 1;
+ }
+
+ blake3_hash_many(parents_array, parents_array_len, 1, key,
+ 0, // Parents always use counter 0.
+ false, flags | PARENT,
+ 0, // Parents have no start flags.
+ 0, // Parents have no end flags.
+ out);
+
+ // If there's an odd child left over, it becomes an output.
+ if (num_chaining_values > 2 * parents_array_len) {
+ memcpy(&out[parents_array_len * BLAKE3_OUT_LEN],
+ &child_chaining_values[2 * parents_array_len * BLAKE3_OUT_LEN],
+ BLAKE3_OUT_LEN);
+ return parents_array_len + 1;
+ } else {
+ return parents_array_len;
+ }
+}
+
+// The wide helper function returns (writes out) an array of chaining values
+// and returns the length of that array. The number of chaining values returned
+// is the dynamically detected SIMD degree, at most MAX_SIMD_DEGREE. Or fewer,
+// if the input is shorter than that many chunks. The reason for maintaining a
+// wide array of chaining values going back up the tree, is to allow the
+// implementation to hash as many parents in parallel as possible.
+//
+// As a special case when the SIMD degree is 1, this function will still return
+// at least 2 outputs. This guarantees that this function doesn't perform the
+// root compression. (If it did, it would use the wrong flags, and also we
+// wouldn't be able to implement extendable output.) Note that this function is
+// not used when the whole input is only 1 chunk long; that's a different
+// codepath.
+//
+// Why not just have the caller split the input on the first update(), instead
+// of implementing this special rule? Because we don't want to limit SIMD or
+// multi-threading parallelism for that update().
+size_t blake3_compress_subtree_wide(const uint8_t *input, size_t input_len,
+ const uint32_t key[8],
+ uint64_t chunk_counter, uint8_t flags,
+ uint8_t *out, bool use_tbb) {
+ // Note that the single chunk case does *not* bump the SIMD degree up to 2
+ // when it is 1. If this implementation adds multi-threading in the future,
+ // this gives us the option of multi-threading even the 2-chunk case, which
+ // can help performance on smaller platforms.
+ if (input_len <= blake3_simd_degree() * BLAKE3_CHUNK_LEN) {
+ return compress_chunks_parallel(input, input_len, key, chunk_counter, flags,
+ out);
+ }
+
+ // With more than simd_degree chunks, we need to recurse. Start by dividing
+ // the input into left and right subtrees. (Note that this is only optimal
+ // as long as the SIMD degree is a power of 2. If we ever get a SIMD degree
+ // of 3 or something, we'll need a more complicated strategy.)
+ size_t left_input_len = left_subtree_len(input_len);
+ size_t right_input_len = input_len - left_input_len;
+ const uint8_t *right_input = &input[left_input_len];
+ uint64_t right_chunk_counter =
+ chunk_counter + (uint64_t)(left_input_len / BLAKE3_CHUNK_LEN);
+
+ // Make space for the child outputs. Here we use MAX_SIMD_DEGREE_OR_2 to
+ // account for the special case of returning 2 outputs when the SIMD degree
+ // is 1.
+ uint8_t cv_array[2 * MAX_SIMD_DEGREE_OR_2 * BLAKE3_OUT_LEN];
+ size_t degree = blake3_simd_degree();
+ if (left_input_len > BLAKE3_CHUNK_LEN && degree == 1) {
+ // The special case: We always use a degree of at least two, to make
+ // sure there are two outputs. Except, as noted above, at the chunk
+ // level, where we allow degree=1. (Note that the 1-chunk-input case is
+ // a different codepath.)
+ degree = 2;
+ }
+ uint8_t *right_cvs = &cv_array[degree * BLAKE3_OUT_LEN];
+
+ // Recurse!
+ size_t left_n = SIZE_MAX;
+ size_t right_n = SIZE_MAX;
+
+#if defined(BLAKE3_USE_TBB)
+ blake3_compress_subtree_wide_join_tbb(
+ key, flags, use_tbb,
+ // left-hand side
+ input, left_input_len, chunk_counter, cv_array, &left_n,
+ // right-hand side
+ right_input, right_input_len, right_chunk_counter, right_cvs, &right_n);
+#else
+ left_n = blake3_compress_subtree_wide(
+ input, left_input_len, key, chunk_counter, flags, cv_array, use_tbb);
+ right_n = blake3_compress_subtree_wide(right_input, right_input_len, key,
+ right_chunk_counter, flags, right_cvs,
+ use_tbb);
+#endif // BLAKE3_USE_TBB
+
+ // The special case again. If simd_degree=1, then we'll have left_n=1 and
+ // right_n=1. Rather than compressing them into a single output, return
+ // them directly, to make sure we always have at least two outputs.
+ if (left_n == 1) {
+ memcpy(out, cv_array, 2 * BLAKE3_OUT_LEN);
+ return 2;
+ }
+
+ // Otherwise, do one layer of parent node compression.
+ size_t num_chaining_values = left_n + right_n;
+ return compress_parents_parallel(cv_array, num_chaining_values, key, flags,
+ out);
+}
+
+// Hash a subtree with compress_subtree_wide(), and then condense the resulting
+// list of chaining values down to a single parent node. Don't compress that
+// last parent node, however. Instead, return its message bytes (the
+// concatenated chaining values of its children). This is necessary when the
+// first call to update() supplies a complete subtree, because the topmost
+// parent node of that subtree could end up being the root. It's also necessary
+// for extended output in the general case.
+//
+// As with compress_subtree_wide(), this function is not used on inputs of 1
+// chunk or less. That's a different codepath.
+INLINE void
+compress_subtree_to_parent_node(const uint8_t *input, size_t input_len,
+ const uint32_t key[8], uint64_t chunk_counter,
+ uint8_t flags, uint8_t out[2 * BLAKE3_OUT_LEN],
+ bool use_tbb) {
+#if defined(BLAKE3_TESTING)
+ assert(input_len > BLAKE3_CHUNK_LEN);
+#endif
+
+ uint8_t cv_array[MAX_SIMD_DEGREE_OR_2 * BLAKE3_OUT_LEN];
+ size_t num_cvs = blake3_compress_subtree_wide(input, input_len, key,
+ chunk_counter, flags, cv_array, use_tbb);
+ assert(num_cvs <= MAX_SIMD_DEGREE_OR_2);
+ // The following loop never executes when MAX_SIMD_DEGREE_OR_2 is 2, because
+ // as we just asserted, num_cvs will always be <=2 in that case. But GCC
+ // (particularly GCC 8.5) can't tell that it never executes, and if NDEBUG is
+ // set then it emits incorrect warnings here. We tried a few different
+ // hacks to silence these, but in the end our hacks just produced different
+ // warnings (see https://github.com/BLAKE3-team/BLAKE3/pull/380). Out of
+ // desperation, we ifdef out this entire loop when we know it's not needed.
+#if MAX_SIMD_DEGREE_OR_2 > 2
+ // If MAX_SIMD_DEGREE_OR_2 is greater than 2 and there's enough input,
+ // compress_subtree_wide() returns more than 2 chaining values. Condense
+ // them into 2 by forming parent nodes repeatedly.
+ uint8_t out_array[MAX_SIMD_DEGREE_OR_2 * BLAKE3_OUT_LEN / 2];
+ while (num_cvs > 2) {
+ num_cvs =
+ compress_parents_parallel(cv_array, num_cvs, key, flags, out_array);
+ memcpy(cv_array, out_array, num_cvs * BLAKE3_OUT_LEN);
+ }
+#endif
+ memcpy(out, cv_array, 2 * BLAKE3_OUT_LEN);
+}
+
+INLINE void hasher_init_base(blake3_hasher *self, const uint32_t key[8],
+ uint8_t flags) {
+ memcpy(self->key, key, BLAKE3_KEY_LEN);
+ chunk_state_init(&self->chunk, key, flags);
+ self->cv_stack_len = 0;
+}
+
+void blake3_hasher_init(blake3_hasher *self) { hasher_init_base(self, IV, 0); }
+
+void blake3_hasher_init_keyed(blake3_hasher *self,
+ const uint8_t key[BLAKE3_KEY_LEN]) {
+ uint32_t key_words[8];
+ load_key_words(key, key_words);
+ hasher_init_base(self, key_words, KEYED_HASH);
+}
+
+void blake3_hasher_init_derive_key_raw(blake3_hasher *self, const void *context,
+ size_t context_len) {
+ blake3_hasher context_hasher;
+ hasher_init_base(&context_hasher, IV, DERIVE_KEY_CONTEXT);
+ blake3_hasher_update(&context_hasher, context, context_len);
+ uint8_t context_key[BLAKE3_KEY_LEN];
+ blake3_hasher_finalize(&context_hasher, context_key, BLAKE3_KEY_LEN);
+ uint32_t context_key_words[8];
+ load_key_words(context_key, context_key_words);
+ hasher_init_base(self, context_key_words, DERIVE_KEY_MATERIAL);
+}
+
+void blake3_hasher_init_derive_key(blake3_hasher *self, const char *context) {
+ blake3_hasher_init_derive_key_raw(self, context, strlen(context));
+}
+
+// As described in hasher_push_cv() below, we do "lazy merging", delaying
+// merges until right before the next CV is about to be added. This is
+// different from the reference implementation. Another difference is that we
+// aren't always merging 1 chunk at a time. Instead, each CV might represent
+// any power-of-two number of chunks, as long as the smaller-above-larger stack
+// order is maintained. Instead of the "count the trailing 0-bits" algorithm
+// described in the spec, we use a "count the total number of 1-bits" variant
+// that doesn't require us to retain the subtree size of the CV on top of the
+// stack. The principle is the same: each CV that should remain in the stack is
+// represented by a 1-bit in the total number of chunks (or bytes) so far.
+INLINE void hasher_merge_cv_stack(blake3_hasher *self, uint64_t total_len) {
+ size_t post_merge_stack_len = (size_t)popcnt(total_len);
+ while (self->cv_stack_len > post_merge_stack_len) {
+ uint8_t *parent_node =
+ &self->cv_stack[(self->cv_stack_len - 2) * BLAKE3_OUT_LEN];
+ output_t output = parent_output(parent_node, self->key, self->chunk.flags);
+ output_chaining_value(&output, parent_node);
+ self->cv_stack_len -= 1;
+ }
+}
+
+// In reference_impl.rs, we merge the new CV with existing CVs from the stack
+// before pushing it. We can do that because we know more input is coming, so
+// we know none of the merges are root.
+//
+// This setting is different. We want to feed as much input as possible to
+// compress_subtree_wide(), without setting aside anything for the chunk_state.
+// If the user gives us 64 KiB, we want to parallelize over all 64 KiB at once
+// as a single subtree, if at all possible.
+//
+// This leads to two problems:
+// 1) This 64 KiB input might be the only call that ever gets made to update.
+// In this case, the root node of the 64 KiB subtree would be the root node
+// of the whole tree, and it would need to be ROOT finalized. We can't
+// compress it until we know.
+// 2) This 64 KiB input might complete a larger tree, whose root node is
+// similarly going to be the root of the whole tree. For example, maybe
+// we have 196 KiB (that is, 128 + 64) hashed so far. We can't compress the
+// node at the root of the 256 KiB subtree until we know how to finalize it.
+//
+// The second problem is solved with "lazy merging". That is, when we're about
+// to add a CV to the stack, we don't merge it with anything first, as the
+// reference impl does. Instead we do merges using the *previous* CV that was
+// added, which is sitting on top of the stack, and we put the new CV
+// (unmerged) on top of the stack afterwards. This guarantees that we never
+// merge the root node until finalize().
+//
+// Solving the first problem requires an additional tool,
+// compress_subtree_to_parent_node(). That function always returns the top
+// *two* chaining values of the subtree it's compressing. We then do lazy
+// merging with each of them separately, so that the second CV will always
+// remain unmerged. (That also helps us support extendable output when we're
+// hashing an input all-at-once.)
+INLINE void hasher_push_cv(blake3_hasher *self, uint8_t new_cv[BLAKE3_OUT_LEN],
+ uint64_t chunk_counter) {
+ hasher_merge_cv_stack(self, chunk_counter);
+ memcpy(&self->cv_stack[self->cv_stack_len * BLAKE3_OUT_LEN], new_cv,
+ BLAKE3_OUT_LEN);
+ self->cv_stack_len += 1;
+}
+
+INLINE void blake3_hasher_update_base(blake3_hasher *self, const void *input,
+ size_t input_len, bool use_tbb) {
+ // Explicitly checking for zero avoids causing UB by passing a null pointer
+ // to memcpy. This comes up in practice with things like:
+ // std::vector v;
+ // blake3_hasher_update(&hasher, v.data(), v.size());
+ if (input_len == 0) {
+ return;
+ }
+
+ const uint8_t *input_bytes = (const uint8_t *)input;
+
+ // If we have some partial chunk bytes in the internal chunk_state, we need
+ // to finish that chunk first.
+ if (chunk_state_len(&self->chunk) > 0) {
+ size_t take = BLAKE3_CHUNK_LEN - chunk_state_len(&self->chunk);
+ if (take > input_len) {
+ take = input_len;
+ }
+ chunk_state_update(&self->chunk, input_bytes, take);
+ input_bytes += take;
+ input_len -= take;
+ // If we've filled the current chunk and there's more coming, finalize this
+ // chunk and proceed. In this case we know it's not the root.
+ if (input_len > 0) {
+ output_t output = chunk_state_output(&self->chunk);
+ uint8_t chunk_cv[32];
+ output_chaining_value(&output, chunk_cv);
+ hasher_push_cv(self, chunk_cv, self->chunk.chunk_counter);
+ chunk_state_reset(&self->chunk, self->key, self->chunk.chunk_counter + 1);
+ } else {
+ return;
+ }
+ }
+
+ // Now the chunk_state is clear, and we have more input. If there's more than
+ // a single chunk (so, definitely not the root chunk), hash the largest whole
+ // subtree we can, with the full benefits of SIMD (and maybe in the future,
+ // multi-threading) parallelism. Two restrictions:
+ // - The subtree has to be a power-of-2 number of chunks. Only subtrees along
+ // the right edge can be incomplete, and we don't know where the right edge
+ // is going to be until we get to finalize().
+ // - The subtree must evenly divide the total number of chunks up until this
+ // point (if total is not 0). If the current incomplete subtree is only
+ // waiting for 1 more chunk, we can't hash a subtree of 4 chunks. We have
+ // to complete the current subtree first.
+ // Because we might need to break up the input to form powers of 2, or to
+ // evenly divide what we already have, this part runs in a loop.
+ while (input_len > BLAKE3_CHUNK_LEN) {
+ size_t subtree_len = round_down_to_power_of_2(input_len);
+ uint64_t count_so_far = self->chunk.chunk_counter * BLAKE3_CHUNK_LEN;
+ // Shrink the subtree_len until it evenly divides the count so far. We know
+ // that subtree_len itself is a power of 2, so we can use a bitmasking
+ // trick instead of an actual remainder operation. (Note that if the caller
+ // consistently passes power-of-2 inputs of the same size, as is hopefully
+ // typical, this loop condition will always fail, and subtree_len will
+ // always be the full length of the input.)
+ //
+ // An aside: We don't have to shrink subtree_len quite this much. For
+ // example, if count_so_far is 1, we could pass 2 chunks to
+ // compress_subtree_to_parent_node. Since we'll get 2 CVs back, we'll still
+ // get the right answer in the end, and we might get to use 2-way SIMD
+ // parallelism. The problem with this optimization, is that it gets us
+ // stuck always hashing 2 chunks. The total number of chunks will remain
+ // odd, and we'll never graduate to higher degrees of parallelism. See
+ // https://github.com/BLAKE3-team/BLAKE3/issues/69.
+ while ((((uint64_t)(subtree_len - 1)) & count_so_far) != 0) {
+ subtree_len /= 2;
+ }
+ // The shrunken subtree_len might now be 1 chunk long. If so, hash that one
+ // chunk by itself. Otherwise, compress the subtree into a pair of CVs.
+ uint64_t subtree_chunks = subtree_len / BLAKE3_CHUNK_LEN;
+ if (subtree_len <= BLAKE3_CHUNK_LEN) {
+ blake3_chunk_state chunk_state;
+ chunk_state_init(&chunk_state, self->key, self->chunk.flags);
+ chunk_state.chunk_counter = self->chunk.chunk_counter;
+ chunk_state_update(&chunk_state, input_bytes, subtree_len);
+ output_t output = chunk_state_output(&chunk_state);
+ uint8_t cv[BLAKE3_OUT_LEN];
+ output_chaining_value(&output, cv);
+ hasher_push_cv(self, cv, chunk_state.chunk_counter);
+ } else {
+ // This is the high-performance happy path, though getting here depends
+ // on the caller giving us a long enough input.
+ uint8_t cv_pair[2 * BLAKE3_OUT_LEN];
+ compress_subtree_to_parent_node(input_bytes, subtree_len, self->key,
+ self->chunk.chunk_counter,
+ self->chunk.flags, cv_pair, use_tbb);
+ hasher_push_cv(self, cv_pair, self->chunk.chunk_counter);
+ hasher_push_cv(self, &cv_pair[BLAKE3_OUT_LEN],
+ self->chunk.chunk_counter + (subtree_chunks / 2));
+ }
+ self->chunk.chunk_counter += subtree_chunks;
+ input_bytes += subtree_len;
+ input_len -= subtree_len;
+ }
+
+ // If there's any remaining input less than a full chunk, add it to the chunk
+ // state. In that case, also do a final merge loop to make sure the subtree
+ // stack doesn't contain any unmerged pairs. The remaining input means we
+ // know these merges are non-root. This merge loop isn't strictly necessary
+ // here, because hasher_push_chunk_cv already does its own merge loop, but it
+ // simplifies blake3_hasher_finalize below.
+ if (input_len > 0) {
+ chunk_state_update(&self->chunk, input_bytes, input_len);
+ hasher_merge_cv_stack(self, self->chunk.chunk_counter);
+ }
+}
+
+void blake3_hasher_update(blake3_hasher *self, const void *input,
+ size_t input_len) {
+ bool use_tbb = false;
+ blake3_hasher_update_base(self, input, input_len, use_tbb);
+}
+
+#if defined(BLAKE3_USE_TBB)
+void blake3_hasher_update_tbb(blake3_hasher *self, const void *input,
+ size_t input_len) {
+ bool use_tbb = true;
+ blake3_hasher_update_base(self, input, input_len, use_tbb);
+}
+#endif // BLAKE3_USE_TBB
+
+void blake3_hasher_finalize(const blake3_hasher *self, uint8_t *out,
+ size_t out_len) {
+ blake3_hasher_finalize_seek(self, 0, out, out_len);
+}
+
+void blake3_hasher_finalize_seek(const blake3_hasher *self, uint64_t seek,
+ uint8_t *out, size_t out_len) {
+ // Explicitly checking for zero avoids causing UB by passing a null pointer
+ // to memcpy. This comes up in practice with things like:
+ // std::vector v;
+ // blake3_hasher_finalize(&hasher, v.data(), v.size());
+ if (out_len == 0) {
+ return;
+ }
+
+ // If the subtree stack is empty, then the current chunk is the root.
+ if (self->cv_stack_len == 0) {
+ output_t output = chunk_state_output(&self->chunk);
+ output_root_bytes(&output, seek, out, out_len);
+ return;
+ }
+ // If there are any bytes in the chunk state, finalize that chunk and do a
+ // roll-up merge between that chunk hash and every subtree in the stack. In
+ // this case, the extra merge loop at the end of blake3_hasher_update
+ // guarantees that none of the subtrees in the stack need to be merged with
+ // each other first. Otherwise, if there are no bytes in the chunk state,
+ // then the top of the stack is a chunk hash, and we start the merge from
+ // that.
+ output_t output;
+ size_t cvs_remaining;
+ if (chunk_state_len(&self->chunk) > 0) {
+ cvs_remaining = self->cv_stack_len;
+ output = chunk_state_output(&self->chunk);
+ } else {
+ // There are always at least 2 CVs in the stack in this case.
+ cvs_remaining = self->cv_stack_len - 2;
+ output = parent_output(&self->cv_stack[cvs_remaining * 32], self->key,
+ self->chunk.flags);
+ }
+ while (cvs_remaining > 0) {
+ cvs_remaining -= 1;
+ uint8_t parent_block[BLAKE3_BLOCK_LEN];
+ memcpy(parent_block, &self->cv_stack[cvs_remaining * 32], 32);
+ output_chaining_value(&output, &parent_block[32]);
+ output = parent_output(parent_block, self->key, self->chunk.flags);
+ }
+ output_root_bytes(&output, seek, out, out_len);
+}
+
+void blake3_hasher_reset(blake3_hasher *self) {
+ chunk_state_reset(&self->chunk, self->key, 0);
+ self->cv_stack_len = 0;
+}
diff --git a/crates/vcore-blake3-raw/vendor/blake3.h b/crates/vcore-blake3-raw/vendor/blake3.h
new file mode 100644
index 0000000..c5b7998
--- /dev/null
+++ b/crates/vcore-blake3-raw/vendor/blake3.h
@@ -0,0 +1,86 @@
+#ifndef BLAKE3_H
+#define BLAKE3_H
+
+#include
+#include
+
+#if !defined(BLAKE3_API)
+# if defined(_WIN32) || defined(__CYGWIN__)
+# if defined(BLAKE3_DLL)
+# if defined(BLAKE3_DLL_EXPORTS)
+# define BLAKE3_API __declspec(dllexport)
+# else
+# define BLAKE3_API __declspec(dllimport)
+# endif
+# define BLAKE3_PRIVATE
+# else
+# define BLAKE3_API
+# define BLAKE3_PRIVATE
+# endif
+# elif __GNUC__ >= 4
+# define BLAKE3_API __attribute__((visibility("default")))
+# define BLAKE3_PRIVATE __attribute__((visibility("hidden")))
+# else
+# define BLAKE3_API
+# define BLAKE3_PRIVATE
+# endif
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define BLAKE3_VERSION_STRING "1.8.7"
+#define BLAKE3_KEY_LEN 32
+#define BLAKE3_OUT_LEN 32
+#define BLAKE3_BLOCK_LEN 64
+#define BLAKE3_CHUNK_LEN 1024
+#define BLAKE3_MAX_DEPTH 54
+
+// This struct is a private implementation detail. It has to be here because
+// it's part of the blake3_hasher structure defined below.
+typedef struct {
+ uint32_t cv[8];
+ uint64_t chunk_counter;
+ uint8_t buf[BLAKE3_BLOCK_LEN];
+ uint8_t buf_len;
+ uint8_t blocks_compressed;
+ uint8_t flags;
+} blake3_chunk_state;
+
+typedef struct {
+ uint32_t key[8];
+ blake3_chunk_state chunk;
+ uint8_t cv_stack_len;
+ // The stack size is MAX_DEPTH + 1 because we do lazy merging. For example,
+ // with 7 chunks, we have 3 entries in the stack. Adding an 8th chunk
+ // requires a 4th entry, rather than merging everything down to 1, because we
+ // don't know whether more input is coming. This is different from how the
+ // reference implementation does things.
+ uint8_t cv_stack[(BLAKE3_MAX_DEPTH + 1) * BLAKE3_OUT_LEN];
+} blake3_hasher;
+
+BLAKE3_API const char *blake3_version(void);
+BLAKE3_API void blake3_hasher_init(blake3_hasher *self);
+BLAKE3_API void blake3_hasher_init_keyed(blake3_hasher *self,
+ const uint8_t key[BLAKE3_KEY_LEN]);
+BLAKE3_API void blake3_hasher_init_derive_key(blake3_hasher *self, const char *context);
+BLAKE3_API void blake3_hasher_init_derive_key_raw(blake3_hasher *self, const void *context,
+ size_t context_len);
+BLAKE3_API void blake3_hasher_update(blake3_hasher *self, const void *input,
+ size_t input_len);
+#if defined(BLAKE3_USE_TBB)
+BLAKE3_API void blake3_hasher_update_tbb(blake3_hasher *self, const void *input,
+ size_t input_len);
+#endif // BLAKE3_USE_TBB
+BLAKE3_API void blake3_hasher_finalize(const blake3_hasher *self, uint8_t *out,
+ size_t out_len);
+BLAKE3_API void blake3_hasher_finalize_seek(const blake3_hasher *self, uint64_t seek,
+ uint8_t *out, size_t out_len);
+BLAKE3_API void blake3_hasher_reset(blake3_hasher *self);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BLAKE3_H */
diff --git a/crates/vcore-blake3-raw/vendor/blake3_dispatch.c b/crates/vcore-blake3-raw/vendor/blake3_dispatch.c
new file mode 100644
index 0000000..14dfbbe
--- /dev/null
+++ b/crates/vcore-blake3-raw/vendor/blake3_dispatch.c
@@ -0,0 +1,332 @@
+#include
+#include
+#include
+
+#include "blake3_impl.h"
+
+#if defined(_MSC_VER)
+#include
+#endif
+
+#if defined(IS_X86)
+#if defined(_MSC_VER)
+#include
+#elif defined(__GNUC__)
+#include
+#else
+#undef IS_X86 /* Unimplemented! */
+#endif
+#endif
+
+#if !defined(BLAKE3_ATOMICS)
+#if defined(__has_include)
+#if __has_include() && !defined(_MSC_VER)
+#define BLAKE3_ATOMICS 1
+#else
+#define BLAKE3_ATOMICS 0
+#endif /* __has_include() && !defined(_MSC_VER) */
+#else
+#define BLAKE3_ATOMICS 0
+#endif /* defined(__has_include) */
+#endif /* BLAKE3_ATOMICS */
+
+#if BLAKE3_ATOMICS
+#define ATOMIC_INT _Atomic int
+#define ATOMIC_LOAD(x) x
+#define ATOMIC_STORE(x, y) x = y
+#elif defined(_MSC_VER)
+#define ATOMIC_INT LONG
+#define ATOMIC_LOAD(x) InterlockedOr(&x, 0)
+#define ATOMIC_STORE(x, y) InterlockedExchange(&x, y)
+#else
+#define ATOMIC_INT int
+#define ATOMIC_LOAD(x) x
+#define ATOMIC_STORE(x, y) x = y
+#endif
+
+#define MAYBE_UNUSED(x) (void)((x))
+
+#if defined(IS_X86)
+static uint64_t xgetbv(void) {
+#if defined(_MSC_VER)
+ return _xgetbv(0);
+#else
+ uint32_t eax = 0, edx = 0;
+ __asm__ __volatile__("xgetbv\n" : "=a"(eax), "=d"(edx) : "c"(0));
+ return ((uint64_t)edx << 32) | eax;
+#endif
+}
+
+static void cpuid(uint32_t out[4], uint32_t id) {
+#if defined(_MSC_VER)
+ __cpuid((int *)out, id);
+#elif defined(__i386__) || defined(_M_IX86)
+ __asm__ __volatile__("movl %%ebx, %1\n"
+ "cpuid\n"
+ "xchgl %1, %%ebx\n"
+ : "=a"(out[0]), "=r"(out[1]), "=c"(out[2]), "=d"(out[3])
+ : "a"(id));
+#else
+ __asm__ __volatile__("cpuid\n"
+ : "=a"(out[0]), "=b"(out[1]), "=c"(out[2]), "=d"(out[3])
+ : "a"(id));
+#endif
+}
+
+static void cpuidex(uint32_t out[4], uint32_t id, uint32_t sid) {
+#if defined(_MSC_VER)
+ __cpuidex((int *)out, id, sid);
+#elif defined(__i386__) || defined(_M_IX86)
+ __asm__ __volatile__("movl %%ebx, %1\n"
+ "cpuid\n"
+ "xchgl %1, %%ebx\n"
+ : "=a"(out[0]), "=r"(out[1]), "=c"(out[2]), "=d"(out[3])
+ : "a"(id), "c"(sid));
+#else
+ __asm__ __volatile__("cpuid\n"
+ : "=a"(out[0]), "=b"(out[1]), "=c"(out[2]), "=d"(out[3])
+ : "a"(id), "c"(sid));
+#endif
+}
+
+
+enum cpu_feature {
+ SSE2 = 1 << 0,
+ SSSE3 = 1 << 1,
+ SSE41 = 1 << 2,
+ AVX = 1 << 3,
+ AVX2 = 1 << 4,
+ AVX512F = 1 << 5,
+ AVX512VL = 1 << 6,
+ /* ... */
+ UNDEFINED = 1 << 30
+};
+
+#if !defined(BLAKE3_TESTING)
+static /* Allow the variable to be controlled manually for testing */
+#endif
+ ATOMIC_INT g_cpu_features = UNDEFINED;
+
+#if !defined(BLAKE3_TESTING)
+static
+#endif
+ enum cpu_feature
+ get_cpu_features(void) {
+
+ /* If TSAN detects a data race here, try compiling with -DBLAKE3_ATOMICS=1 */
+ enum cpu_feature features = ATOMIC_LOAD(g_cpu_features);
+ if (features != UNDEFINED) {
+ return features;
+ } else {
+#if defined(IS_X86)
+ uint32_t regs[4] = {0};
+ uint32_t *eax = ®s[0], *ebx = ®s[1], *ecx = ®s[2], *edx = ®s[3];
+ (void)edx;
+ features = 0;
+ cpuid(regs, 0);
+ const int max_id = *eax;
+ cpuid(regs, 1);
+#if defined(__amd64__) || defined(_M_X64)
+ features |= SSE2;
+#else
+ if (*edx & (1UL << 26))
+ features |= SSE2;
+#endif
+ if (*ecx & (1UL << 9))
+ features |= SSSE3;
+ if (*ecx & (1UL << 19))
+ features |= SSE41;
+
+ if (*ecx & (1UL << 27)) { // OSXSAVE
+ const uint64_t mask = xgetbv();
+ if ((mask & 6) == 6) { // SSE and AVX states
+ if (*ecx & (1UL << 28))
+ features |= AVX;
+ if (max_id >= 7) {
+ cpuidex(regs, 7, 0);
+ if (*ebx & (1UL << 5))
+ features |= AVX2;
+ if ((mask & 224) == 224) { // Opmask, ZMM_Hi256, Hi16_Zmm
+ if (*ebx & (1UL << 31))
+ features |= AVX512VL;
+ if (*ebx & (1UL << 16))
+ features |= AVX512F;
+ }
+ }
+ }
+ }
+ ATOMIC_STORE(g_cpu_features, features);
+ return features;
+#else
+ /* How to detect NEON? */
+ return 0;
+#endif
+ }
+}
+#endif
+
+void blake3_compress_in_place(uint32_t cv[8],
+ const uint8_t block[BLAKE3_BLOCK_LEN],
+ uint8_t block_len, uint64_t counter,
+ uint8_t flags) {
+#if defined(IS_X86)
+ const enum cpu_feature features = get_cpu_features();
+ MAYBE_UNUSED(features);
+#if !defined(BLAKE3_NO_AVX512)
+ if (features & AVX512VL) {
+ blake3_compress_in_place_avx512(cv, block, block_len, counter, flags);
+ return;
+ }
+#endif
+#if !defined(BLAKE3_NO_SSE41)
+ if (features & SSE41) {
+ blake3_compress_in_place_sse41(cv, block, block_len, counter, flags);
+ return;
+ }
+#endif
+#if !defined(BLAKE3_NO_SSE2)
+ if (features & SSE2) {
+ blake3_compress_in_place_sse2(cv, block, block_len, counter, flags);
+ return;
+ }
+#endif
+#endif
+ blake3_compress_in_place_portable(cv, block, block_len, counter, flags);
+}
+
+void blake3_compress_xof(const uint32_t cv[8],
+ const uint8_t block[BLAKE3_BLOCK_LEN],
+ uint8_t block_len, uint64_t counter, uint8_t flags,
+ uint8_t out[64]) {
+#if defined(IS_X86)
+ const enum cpu_feature features = get_cpu_features();
+ MAYBE_UNUSED(features);
+#if !defined(BLAKE3_NO_AVX512)
+ if (features & AVX512VL) {
+ blake3_compress_xof_avx512(cv, block, block_len, counter, flags, out);
+ return;
+ }
+#endif
+#if !defined(BLAKE3_NO_SSE41)
+ if (features & SSE41) {
+ blake3_compress_xof_sse41(cv, block, block_len, counter, flags, out);
+ return;
+ }
+#endif
+#if !defined(BLAKE3_NO_SSE2)
+ if (features & SSE2) {
+ blake3_compress_xof_sse2(cv, block, block_len, counter, flags, out);
+ return;
+ }
+#endif
+#endif
+ blake3_compress_xof_portable(cv, block, block_len, counter, flags, out);
+}
+
+
+void blake3_xof_many(const uint32_t cv[8],
+ const uint8_t block[BLAKE3_BLOCK_LEN],
+ uint8_t block_len, uint64_t counter, uint8_t flags,
+ uint8_t out[64], size_t outblocks) {
+ if (outblocks == 0) {
+ // The current assembly implementation always outputs at least 1 block.
+ return;
+ }
+#if defined(IS_X86)
+ const enum cpu_feature features = get_cpu_features();
+ MAYBE_UNUSED(features);
+#if !defined(_WIN32) && !defined(__CYGWIN__) && !defined(BLAKE3_NO_AVX512)
+ if (features & AVX512VL) {
+ blake3_xof_many_avx512(cv, block, block_len, counter, flags, out, outblocks);
+ return;
+ }
+#endif
+#endif
+ for(size_t i = 0; i < outblocks; ++i) {
+ blake3_compress_xof(cv, block, block_len, counter + i, flags, out + 64*i);
+ }
+}
+
+void blake3_hash_many(const uint8_t *const *inputs, size_t num_inputs,
+ size_t blocks, const uint32_t key[8], uint64_t counter,
+ bool increment_counter, uint8_t flags,
+ uint8_t flags_start, uint8_t flags_end, uint8_t *out) {
+#if defined(IS_X86)
+ const enum cpu_feature features = get_cpu_features();
+ MAYBE_UNUSED(features);
+#if !defined(BLAKE3_NO_AVX512)
+ if ((features & (AVX512F|AVX512VL)) == (AVX512F|AVX512VL)) {
+ blake3_hash_many_avx512(inputs, num_inputs, blocks, key, counter,
+ increment_counter, flags, flags_start, flags_end,
+ out);
+ return;
+ }
+#endif
+#if !defined(BLAKE3_NO_AVX2)
+ if (features & AVX2) {
+ blake3_hash_many_avx2(inputs, num_inputs, blocks, key, counter,
+ increment_counter, flags, flags_start, flags_end,
+ out);
+ return;
+ }
+#endif
+#if !defined(BLAKE3_NO_SSE41)
+ if (features & SSE41) {
+ blake3_hash_many_sse41(inputs, num_inputs, blocks, key, counter,
+ increment_counter, flags, flags_start, flags_end,
+ out);
+ return;
+ }
+#endif
+#if !defined(BLAKE3_NO_SSE2)
+ if (features & SSE2) {
+ blake3_hash_many_sse2(inputs, num_inputs, blocks, key, counter,
+ increment_counter, flags, flags_start, flags_end,
+ out);
+ return;
+ }
+#endif
+#endif
+
+#if BLAKE3_USE_NEON == 1
+ blake3_hash_many_neon(inputs, num_inputs, blocks, key, counter,
+ increment_counter, flags, flags_start, flags_end, out);
+ return;
+#endif
+
+ blake3_hash_many_portable(inputs, num_inputs, blocks, key, counter,
+ increment_counter, flags, flags_start, flags_end,
+ out);
+}
+
+// The dynamically detected SIMD degree of the current platform.
+size_t blake3_simd_degree(void) {
+#if defined(IS_X86)
+ const enum cpu_feature features = get_cpu_features();
+ MAYBE_UNUSED(features);
+#if !defined(BLAKE3_NO_AVX512)
+ if ((features & (AVX512F|AVX512VL)) == (AVX512F|AVX512VL)) {
+ return 16;
+ }
+#endif
+#if !defined(BLAKE3_NO_AVX2)
+ if (features & AVX2) {
+ return 8;
+ }
+#endif
+#if !defined(BLAKE3_NO_SSE41)
+ if (features & SSE41) {
+ return 4;
+ }
+#endif
+#if !defined(BLAKE3_NO_SSE2)
+ if (features & SSE2) {
+ return 4;
+ }
+#endif
+#endif
+#if BLAKE3_USE_NEON == 1
+ return 4;
+#endif
+ return 1;
+}
diff --git a/crates/vcore-blake3-raw/vendor/blake3_impl.h b/crates/vcore-blake3-raw/vendor/blake3_impl.h
new file mode 100644
index 0000000..88e71e4
--- /dev/null
+++ b/crates/vcore-blake3-raw/vendor/blake3_impl.h
@@ -0,0 +1,333 @@
+#ifndef BLAKE3_IMPL_H
+#define BLAKE3_IMPL_H
+
+#include
+#include
+#include
+#include
+#include
+
+#include "blake3.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// internal flags
+enum blake3_flags {
+ CHUNK_START = 1 << 0,
+ CHUNK_END = 1 << 1,
+ PARENT = 1 << 2,
+ ROOT = 1 << 3,
+ KEYED_HASH = 1 << 4,
+ DERIVE_KEY_CONTEXT = 1 << 5,
+ DERIVE_KEY_MATERIAL = 1 << 6,
+};
+
+// This C implementation tries to support recent versions of GCC, Clang, and
+// MSVC.
+#if defined(_MSC_VER)
+#define INLINE static __forceinline
+#else
+#define INLINE static inline __attribute__((always_inline))
+#endif
+
+#ifdef __cplusplus
+#define NOEXCEPT noexcept
+#else
+#define NOEXCEPT
+#endif
+
+#if (defined(__x86_64__) || defined(_M_X64)) && !defined(_M_ARM64EC)
+#define IS_X86
+#define IS_X86_64
+#endif
+
+#if defined(__i386__) || defined(_M_IX86)
+#define IS_X86
+#define IS_X86_32
+#endif
+
+#if defined(__aarch64__) || defined(_M_ARM64) || defined(_M_ARM64EC)
+#define IS_AARCH64
+#endif
+
+#if defined(IS_X86)
+#if defined(_MSC_VER)
+#include
+#endif
+#endif
+
+#if !defined(BLAKE3_USE_NEON)
+ // If BLAKE3_USE_NEON not manually set, autodetect based on AArch64ness
+ #if defined(IS_AARCH64)
+ #if defined(__ARM_BIG_ENDIAN)
+ #define BLAKE3_USE_NEON 0
+ #else
+ #define BLAKE3_USE_NEON 1
+ #endif
+ #else
+ #define BLAKE3_USE_NEON 0
+ #endif
+#endif
+
+#if defined(IS_X86)
+#define MAX_SIMD_DEGREE 16
+#elif BLAKE3_USE_NEON == 1
+#define MAX_SIMD_DEGREE 4
+#else
+#define MAX_SIMD_DEGREE 1
+#endif
+
+// There are some places where we want a static size that's equal to the
+// MAX_SIMD_DEGREE, but also at least 2.
+#define MAX_SIMD_DEGREE_OR_2 (MAX_SIMD_DEGREE > 2 ? MAX_SIMD_DEGREE : 2)
+
+static const uint32_t IV[8] = {0x6A09E667UL, 0xBB67AE85UL, 0x3C6EF372UL,
+ 0xA54FF53AUL, 0x510E527FUL, 0x9B05688CUL,
+ 0x1F83D9ABUL, 0x5BE0CD19UL};
+
+static const uint8_t MSG_SCHEDULE[7][16] = {
+ {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15},
+ {2, 6, 3, 10, 7, 0, 4, 13, 1, 11, 12, 5, 9, 14, 15, 8},
+ {3, 4, 10, 12, 13, 2, 7, 14, 6, 5, 9, 0, 11, 15, 8, 1},
+ {10, 7, 12, 9, 14, 3, 13, 15, 4, 0, 11, 2, 5, 8, 1, 6},
+ {12, 13, 9, 11, 15, 10, 14, 8, 7, 2, 5, 3, 0, 1, 6, 4},
+ {9, 14, 11, 5, 8, 12, 15, 1, 13, 3, 0, 10, 2, 6, 4, 7},
+ {11, 15, 5, 0, 1, 9, 8, 6, 14, 10, 2, 12, 3, 4, 7, 13},
+};
+
+/* Find index of the highest set bit */
+/* x is assumed to be nonzero. */
+static unsigned int highest_one(uint64_t x) {
+#if defined(__GNUC__) || defined(__clang__)
+ return 63 ^ (unsigned int)__builtin_clzll(x);
+#elif defined(_MSC_VER) && defined(IS_X86_64)
+ unsigned long index;
+ _BitScanReverse64(&index, x);
+ return index;
+#elif defined(_MSC_VER) && defined(IS_X86_32)
+ if(x >> 32) {
+ unsigned long index;
+ _BitScanReverse(&index, (unsigned long)(x >> 32));
+ return 32 + index;
+ } else {
+ unsigned long index;
+ _BitScanReverse(&index, (unsigned long)x);
+ return index;
+ }
+#else
+ unsigned int c = 0;
+ if(x & 0xffffffff00000000ULL) { x >>= 32; c += 32; }
+ if(x & 0x00000000ffff0000ULL) { x >>= 16; c += 16; }
+ if(x & 0x000000000000ff00ULL) { x >>= 8; c += 8; }
+ if(x & 0x00000000000000f0ULL) { x >>= 4; c += 4; }
+ if(x & 0x000000000000000cULL) { x >>= 2; c += 2; }
+ if(x & 0x0000000000000002ULL) { c += 1; }
+ return c;
+#endif
+}
+
+// Count the number of 1 bits.
+INLINE unsigned int popcnt(uint64_t x) {
+#if defined(__GNUC__) || defined(__clang__)
+ return (unsigned int)__builtin_popcountll(x);
+#else
+ unsigned int count = 0;
+ while (x != 0) {
+ count += 1;
+ x &= x - 1;
+ }
+ return count;
+#endif
+}
+
+// Largest power of two less than or equal to x. As a special case, returns 1
+// when x is 0.
+INLINE uint64_t round_down_to_power_of_2(uint64_t x) {
+ return 1ULL << highest_one(x | 1);
+}
+
+INLINE uint32_t counter_low(uint64_t counter) { return (uint32_t)counter; }
+
+INLINE uint32_t counter_high(uint64_t counter) {
+ return (uint32_t)(counter >> 32);
+}
+
+INLINE uint32_t load32(const void *src) {
+ const uint8_t *p = (const uint8_t *)src;
+ return ((uint32_t)(p[0]) << 0) | ((uint32_t)(p[1]) << 8) |
+ ((uint32_t)(p[2]) << 16) | ((uint32_t)(p[3]) << 24);
+}
+
+INLINE void load_key_words(const uint8_t key[BLAKE3_KEY_LEN],
+ uint32_t key_words[8]) {
+ key_words[0] = load32(&key[0 * 4]);
+ key_words[1] = load32(&key[1 * 4]);
+ key_words[2] = load32(&key[2 * 4]);
+ key_words[3] = load32(&key[3 * 4]);
+ key_words[4] = load32(&key[4 * 4]);
+ key_words[5] = load32(&key[5 * 4]);
+ key_words[6] = load32(&key[6 * 4]);
+ key_words[7] = load32(&key[7 * 4]);
+}
+
+INLINE void load_block_words(const uint8_t block[BLAKE3_BLOCK_LEN],
+ uint32_t block_words[16]) {
+ for (size_t i = 0; i < 16; i++) {
+ block_words[i] = load32(&block[i * 4]);
+ }
+}
+
+INLINE void store32(void *dst, uint32_t w) {
+ uint8_t *p = (uint8_t *)dst;
+ p[0] = (uint8_t)(w >> 0);
+ p[1] = (uint8_t)(w >> 8);
+ p[2] = (uint8_t)(w >> 16);
+ p[3] = (uint8_t)(w >> 24);
+}
+
+INLINE void store_cv_words(uint8_t bytes_out[32], uint32_t cv_words[8]) {
+ store32(&bytes_out[0 * 4], cv_words[0]);
+ store32(&bytes_out[1 * 4], cv_words[1]);
+ store32(&bytes_out[2 * 4], cv_words[2]);
+ store32(&bytes_out[3 * 4], cv_words[3]);
+ store32(&bytes_out[4 * 4], cv_words[4]);
+ store32(&bytes_out[5 * 4], cv_words[5]);
+ store32(&bytes_out[6 * 4], cv_words[6]);
+ store32(&bytes_out[7 * 4], cv_words[7]);
+}
+
+void blake3_compress_in_place(uint32_t cv[8],
+ const uint8_t block[BLAKE3_BLOCK_LEN],
+ uint8_t block_len, uint64_t counter,
+ uint8_t flags);
+
+void blake3_compress_xof(const uint32_t cv[8],
+ const uint8_t block[BLAKE3_BLOCK_LEN],
+ uint8_t block_len, uint64_t counter, uint8_t flags,
+ uint8_t out[64]);
+
+void blake3_xof_many(const uint32_t cv[8],
+ const uint8_t block[BLAKE3_BLOCK_LEN],
+ uint8_t block_len, uint64_t counter, uint8_t flags,
+ uint8_t out[64], size_t outblocks);
+
+void blake3_hash_many(const uint8_t *const *inputs, size_t num_inputs,
+ size_t blocks, const uint32_t key[8], uint64_t counter,
+ bool increment_counter, uint8_t flags,
+ uint8_t flags_start, uint8_t flags_end, uint8_t *out);
+
+size_t blake3_simd_degree(void);
+
+BLAKE3_PRIVATE size_t blake3_compress_subtree_wide(const uint8_t *input, size_t input_len,
+ const uint32_t key[8],
+ uint64_t chunk_counter, uint8_t flags,
+ uint8_t *out, bool use_tbb);
+
+#if defined(BLAKE3_USE_TBB)
+BLAKE3_PRIVATE void blake3_compress_subtree_wide_join_tbb(
+ // shared params
+ const uint32_t key[8], uint8_t flags, bool use_tbb,
+ // left-hand side params
+ const uint8_t *l_input, size_t l_input_len, uint64_t l_chunk_counter,
+ uint8_t *l_cvs, size_t *l_n,
+ // right-hand side params
+ const uint8_t *r_input, size_t r_input_len, uint64_t r_chunk_counter,
+ uint8_t *r_cvs, size_t *r_n) NOEXCEPT;
+#endif
+
+// Declarations for implementation-specific functions.
+void blake3_compress_in_place_portable(uint32_t cv[8],
+ const uint8_t block[BLAKE3_BLOCK_LEN],
+ uint8_t block_len, uint64_t counter,
+ uint8_t flags);
+
+void blake3_compress_xof_portable(const uint32_t cv[8],
+ const uint8_t block[BLAKE3_BLOCK_LEN],
+ uint8_t block_len, uint64_t counter,
+ uint8_t flags, uint8_t out[64]);
+
+void blake3_hash_many_portable(const uint8_t *const *inputs, size_t num_inputs,
+ size_t blocks, const uint32_t key[8],
+ uint64_t counter, bool increment_counter,
+ uint8_t flags, uint8_t flags_start,
+ uint8_t flags_end, uint8_t *out);
+
+#if defined(IS_X86)
+#if !defined(BLAKE3_NO_SSE2)
+void blake3_compress_in_place_sse2(uint32_t cv[8],
+ const uint8_t block[BLAKE3_BLOCK_LEN],
+ uint8_t block_len, uint64_t counter,
+ uint8_t flags);
+void blake3_compress_xof_sse2(const uint32_t cv[8],
+ const uint8_t block[BLAKE3_BLOCK_LEN],
+ uint8_t block_len, uint64_t counter,
+ uint8_t flags, uint8_t out[64]);
+void blake3_hash_many_sse2(const uint8_t *const *inputs, size_t num_inputs,
+ size_t blocks, const uint32_t key[8],
+ uint64_t counter, bool increment_counter,
+ uint8_t flags, uint8_t flags_start,
+ uint8_t flags_end, uint8_t *out);
+#endif
+#if !defined(BLAKE3_NO_SSE41)
+void blake3_compress_in_place_sse41(uint32_t cv[8],
+ const uint8_t block[BLAKE3_BLOCK_LEN],
+ uint8_t block_len, uint64_t counter,
+ uint8_t flags);
+void blake3_compress_xof_sse41(const uint32_t cv[8],
+ const uint8_t block[BLAKE3_BLOCK_LEN],
+ uint8_t block_len, uint64_t counter,
+ uint8_t flags, uint8_t out[64]);
+void blake3_hash_many_sse41(const uint8_t *const *inputs, size_t num_inputs,
+ size_t blocks, const uint32_t key[8],
+ uint64_t counter, bool increment_counter,
+ uint8_t flags, uint8_t flags_start,
+ uint8_t flags_end, uint8_t *out);
+#endif
+#if !defined(BLAKE3_NO_AVX2)
+void blake3_hash_many_avx2(const uint8_t *const *inputs, size_t num_inputs,
+ size_t blocks, const uint32_t key[8],
+ uint64_t counter, bool increment_counter,
+ uint8_t flags, uint8_t flags_start,
+ uint8_t flags_end, uint8_t *out);
+#endif
+#if !defined(BLAKE3_NO_AVX512)
+void blake3_compress_in_place_avx512(uint32_t cv[8],
+ const uint8_t block[BLAKE3_BLOCK_LEN],
+ uint8_t block_len, uint64_t counter,
+ uint8_t flags);
+
+void blake3_compress_xof_avx512(const uint32_t cv[8],
+ const uint8_t block[BLAKE3_BLOCK_LEN],
+ uint8_t block_len, uint64_t counter,
+ uint8_t flags, uint8_t out[64]);
+
+void blake3_hash_many_avx512(const uint8_t *const *inputs, size_t num_inputs,
+ size_t blocks, const uint32_t key[8],
+ uint64_t counter, bool increment_counter,
+ uint8_t flags, uint8_t flags_start,
+ uint8_t flags_end, uint8_t *out);
+
+#if !defined(_WIN32) && !defined(__CYGWIN__)
+void blake3_xof_many_avx512(const uint32_t cv[8],
+ const uint8_t block[BLAKE3_BLOCK_LEN],
+ uint8_t block_len, uint64_t counter, uint8_t flags,
+ uint8_t* out, size_t outblocks);
+#endif
+#endif
+#endif
+
+#if BLAKE3_USE_NEON == 1
+void blake3_hash_many_neon(const uint8_t *const *inputs, size_t num_inputs,
+ size_t blocks, const uint32_t key[8],
+ uint64_t counter, bool increment_counter,
+ uint8_t flags, uint8_t flags_start,
+ uint8_t flags_end, uint8_t *out);
+#endif
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BLAKE3_IMPL_H */
diff --git a/crates/vcore-blake3-raw/vendor/blake3_portable.c b/crates/vcore-blake3-raw/vendor/blake3_portable.c
new file mode 100644
index 0000000..062dd1b
--- /dev/null
+++ b/crates/vcore-blake3-raw/vendor/blake3_portable.c
@@ -0,0 +1,160 @@
+#include "blake3_impl.h"
+#include
+
+INLINE uint32_t rotr32(uint32_t w, uint32_t c) {
+ return (w >> c) | (w << (32 - c));
+}
+
+INLINE void g(uint32_t *state, size_t a, size_t b, size_t c, size_t d,
+ uint32_t x, uint32_t y) {
+ state[a] = state[a] + state[b] + x;
+ state[d] = rotr32(state[d] ^ state[a], 16);
+ state[c] = state[c] + state[d];
+ state[b] = rotr32(state[b] ^ state[c], 12);
+ state[a] = state[a] + state[b] + y;
+ state[d] = rotr32(state[d] ^ state[a], 8);
+ state[c] = state[c] + state[d];
+ state[b] = rotr32(state[b] ^ state[c], 7);
+}
+
+INLINE void round_fn(uint32_t state[16], const uint32_t *msg, size_t round) {
+ // Select the message schedule based on the round.
+ const uint8_t *schedule = MSG_SCHEDULE[round];
+
+ // Mix the columns.
+ g(state, 0, 4, 8, 12, msg[schedule[0]], msg[schedule[1]]);
+ g(state, 1, 5, 9, 13, msg[schedule[2]], msg[schedule[3]]);
+ g(state, 2, 6, 10, 14, msg[schedule[4]], msg[schedule[5]]);
+ g(state, 3, 7, 11, 15, msg[schedule[6]], msg[schedule[7]]);
+
+ // Mix the rows.
+ g(state, 0, 5, 10, 15, msg[schedule[8]], msg[schedule[9]]);
+ g(state, 1, 6, 11, 12, msg[schedule[10]], msg[schedule[11]]);
+ g(state, 2, 7, 8, 13, msg[schedule[12]], msg[schedule[13]]);
+ g(state, 3, 4, 9, 14, msg[schedule[14]], msg[schedule[15]]);
+}
+
+INLINE void compress_pre(uint32_t state[16], const uint32_t cv[8],
+ const uint8_t block[BLAKE3_BLOCK_LEN],
+ uint8_t block_len, uint64_t counter, uint8_t flags) {
+ uint32_t block_words[16];
+ block_words[0] = load32(block + 4 * 0);
+ block_words[1] = load32(block + 4 * 1);
+ block_words[2] = load32(block + 4 * 2);
+ block_words[3] = load32(block + 4 * 3);
+ block_words[4] = load32(block + 4 * 4);
+ block_words[5] = load32(block + 4 * 5);
+ block_words[6] = load32(block + 4 * 6);
+ block_words[7] = load32(block + 4 * 7);
+ block_words[8] = load32(block + 4 * 8);
+ block_words[9] = load32(block + 4 * 9);
+ block_words[10] = load32(block + 4 * 10);
+ block_words[11] = load32(block + 4 * 11);
+ block_words[12] = load32(block + 4 * 12);
+ block_words[13] = load32(block + 4 * 13);
+ block_words[14] = load32(block + 4 * 14);
+ block_words[15] = load32(block + 4 * 15);
+
+ state[0] = cv[0];
+ state[1] = cv[1];
+ state[2] = cv[2];
+ state[3] = cv[3];
+ state[4] = cv[4];
+ state[5] = cv[5];
+ state[6] = cv[6];
+ state[7] = cv[7];
+ state[8] = IV[0];
+ state[9] = IV[1];
+ state[10] = IV[2];
+ state[11] = IV[3];
+ state[12] = counter_low(counter);
+ state[13] = counter_high(counter);
+ state[14] = (uint32_t)block_len;
+ state[15] = (uint32_t)flags;
+
+ round_fn(state, &block_words[0], 0);
+ round_fn(state, &block_words[0], 1);
+ round_fn(state, &block_words[0], 2);
+ round_fn(state, &block_words[0], 3);
+ round_fn(state, &block_words[0], 4);
+ round_fn(state, &block_words[0], 5);
+ round_fn(state, &block_words[0], 6);
+}
+
+void blake3_compress_in_place_portable(uint32_t cv[8],
+ const uint8_t block[BLAKE3_BLOCK_LEN],
+ uint8_t block_len, uint64_t counter,
+ uint8_t flags) {
+ uint32_t state[16];
+ compress_pre(state, cv, block, block_len, counter, flags);
+ cv[0] = state[0] ^ state[8];
+ cv[1] = state[1] ^ state[9];
+ cv[2] = state[2] ^ state[10];
+ cv[3] = state[3] ^ state[11];
+ cv[4] = state[4] ^ state[12];
+ cv[5] = state[5] ^ state[13];
+ cv[6] = state[6] ^ state[14];
+ cv[7] = state[7] ^ state[15];
+}
+
+void blake3_compress_xof_portable(const uint32_t cv[8],
+ const uint8_t block[BLAKE3_BLOCK_LEN],
+ uint8_t block_len, uint64_t counter,
+ uint8_t flags, uint8_t out[64]) {
+ uint32_t state[16];
+ compress_pre(state, cv, block, block_len, counter, flags);
+
+ store32(&out[0 * 4], state[0] ^ state[8]);
+ store32(&out[1 * 4], state[1] ^ state[9]);
+ store32(&out[2 * 4], state[2] ^ state[10]);
+ store32(&out[3 * 4], state[3] ^ state[11]);
+ store32(&out[4 * 4], state[4] ^ state[12]);
+ store32(&out[5 * 4], state[5] ^ state[13]);
+ store32(&out[6 * 4], state[6] ^ state[14]);
+ store32(&out[7 * 4], state[7] ^ state[15]);
+ store32(&out[8 * 4], state[8] ^ cv[0]);
+ store32(&out[9 * 4], state[9] ^ cv[1]);
+ store32(&out[10 * 4], state[10] ^ cv[2]);
+ store32(&out[11 * 4], state[11] ^ cv[3]);
+ store32(&out[12 * 4], state[12] ^ cv[4]);
+ store32(&out[13 * 4], state[13] ^ cv[5]);
+ store32(&out[14 * 4], state[14] ^ cv[6]);
+ store32(&out[15 * 4], state[15] ^ cv[7]);
+}
+
+INLINE void hash_one_portable(const uint8_t *input, size_t blocks,
+ const uint32_t key[8], uint64_t counter,
+ uint8_t flags, uint8_t flags_start,
+ uint8_t flags_end, uint8_t out[BLAKE3_OUT_LEN]) {
+ uint32_t cv[8];
+ memcpy(cv, key, BLAKE3_KEY_LEN);
+ uint8_t block_flags = flags | flags_start;
+ while (blocks > 0) {
+ if (blocks == 1) {
+ block_flags |= flags_end;
+ }
+ blake3_compress_in_place_portable(cv, input, BLAKE3_BLOCK_LEN, counter,
+ block_flags);
+ input = &input[BLAKE3_BLOCK_LEN];
+ blocks -= 1;
+ block_flags = flags;
+ }
+ store_cv_words(out, cv);
+}
+
+void blake3_hash_many_portable(const uint8_t *const *inputs, size_t num_inputs,
+ size_t blocks, const uint32_t key[8],
+ uint64_t counter, bool increment_counter,
+ uint8_t flags, uint8_t flags_start,
+ uint8_t flags_end, uint8_t *out) {
+ while (num_inputs > 0) {
+ hash_one_portable(inputs[0], blocks, key, counter, flags, flags_start,
+ flags_end, out);
+ if (increment_counter) {
+ counter += 1;
+ }
+ inputs += 1;
+ num_inputs -= 1;
+ out = &out[BLAKE3_OUT_LEN];
+ }
+}
diff --git a/crates/vcore-netstack/Cargo.toml b/crates/vcore-netstack/Cargo.toml
index 7bd6537..4717418 100644
--- a/crates/vcore-netstack/Cargo.toml
+++ b/crates/vcore-netstack/Cargo.toml
@@ -9,7 +9,7 @@ description = "Bounded userspace IPv4/IPv6 TCP and UDP netstack for VCore"
[dependencies]
bytes = "1"
futures-util = "0.3"
-smoltcp = { version = "0.13", default-features = false, features = [
+smoltcp = { version = "0.14", default-features = false, features = [
"std",
"medium-ip",
"auto-icmp-echo-reply",
diff --git a/docs/README.md b/docs/README.md
index f09665f..5dc4c1c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,48 +1,34 @@
# VCore 文档
-本目录只描述当前实现和仍然有效的开发约束。历史方案、阶段计划、一次性实验记录、旧包哈希和第三方实现对比不属于公共文档；源代码、测试与本文档不一致时视为缺陷。
+本文档只维护当前契约、有效约束和发布边界。历史方案、阶段报告与已取消能力留在 Git 历史，不另建归档副本。行为以当前源码、测试和契约为准，不一致时一起修正。
-## 公共契约
+## 配置与接口
-1. [配置协议](config.yaml)：配置修订版 14 的完整 YAML 示例、静态 `select` 代理组及组上游和严格字段边界。
-2. [Invoke API](invoke-api.md)：API v5 的请求格式、生命周期和平台回调。
-3. [AnyTLS 出站](anytls.md)：TLS、会话复用、填充、TCP/UoT 和清理语义。
-4. [REALITY V1 协议](reality-wire-protocol.md)：握手、认证、连接状态和失败边界。
-5. [运行时 Controller](controller-api.md)：Bearer 鉴权、实时代理组选择和四字段 TUN 流量快照。
-6. [DNS 与 ICMP](tun-icmp-dns.md)：TUN DNS、代理组出口、缓存、故障转移和本地 Echo Reply。
-7. [GeoData](geodata.md)：规则、资产更新、匹配器和资源上限。
-8. [TUN 平台层](tun-platform.md)：文件描述符、原始 IP 包和平台所有权。
-9. [HTTP 代理入站](http-proxy.md)：本机 / 共享监听、逐请求认证、消息定界、CONNECT / Upgrade 和同步停止。
-10. [SOCKS5 代理入站](socks5-proxy.md)：CONNECT、授权 UDP 关联、双栈与同端口监听、来源隔离和回收。
-11. [Shadowsocks 2022 出站](shadowsocks.md)：官方依赖、配置/IO 适配、AWS-LC 局部例外、已知风险与未完成互通门槛。
+- [配置协议](config.yaml)：严格 YAML、节点、静态 select 组、DNS 与规则。
+- [Invoke API](invoke-api.md)：请求格式、生命周期、平台回调与内联配置。
+- [Controller](controller-api.md)：认证、运行中组选择和 TUN 流量。
+- [入站](inbounds.md)：HTTP 转发/隧道、SOCKS5 TCP/授权 UDP、监听及认证。
+- [出站](outbounds.md)：SOCKS5、AnyTLS、Trojan、VMess AEAD、Hysteria2、SS 2022。
+- [VLESS](vless.md)：传输、Vision、Encryption、REALITY、JLS、静态 ECH。
+- [XHTTP 与 sing-mux](xhttp.md)：双腿、H1/H2/H3、连接池及复用。
+- [TLS 证书与指纹](tls-client-fingerprint.md)：证书 pin、ClientHello 模板、身份与缓存。
+- [REALITY 线协议](reality-wire-protocol.md)：认证、密钥与失败边界。
-## 平台与运行架构
+## 运行与平台
-1. [Windows VPN 平台边界](windows-vpn.md)：官方 VPN API、包缓冲区、路由、物理网络绑定和安装包约束。
-2. [Windows 会话运行时](windows-session-runtime.md)：Provider、Session Host、包通道和生命周期。
-3. [运行时资源策略](runtime-resource-policy.md)：局部容量、取消、回收和遥测原则。
-4. [rustls REALITY 依赖](rustls-reality-release.md)：自有 fork 的边界和发布要求。
-5. [Windows UWP VPN 最小集成](../example/windows-uwp/README.md)：同包 manifest、完全信任宿主和可运行 demo。
+- [DNS 与 ICMP](tun-icmp-dns.md)、[GeoData](geodata.md)。
+- [资源策略](runtime-resource-policy.md)：局部预算、所有权、取消和观测。
+- [TUN 平台](tun-platform.md)、[Windows VPN](windows-vpn.md)。
+- [TLS 依赖与发布](tls-dependencies.md)：来源、provider、fork 与升级门禁。
+- [Windows 最小集成示例](../example/windows-uwp/README.md)。
-## 证据与维护
+## 开发与验证
-- [验收矩阵](acceptance.md)：自动化覆盖、实机覆盖和未完成的发布门禁。
-- [架构决策](adr/)：仍然有效的系统级决策。
-- [开发上下文](../CONTEXT.md)：领域词汇和模块边界。
-- [构建与检查](../scripts/README.md)：统一脚本、产物和环境变量。
+- [构建与检查](../scripts/README.md)、[测试入口](../tests/README.md)。
+- [测试隔离](testing-isolation.md)：所有网络服务端必须容器化。
+- [验收边界](acceptance.md)：本地、CI、设备和发布证据分别记录。
+- [领域上下文](../CONTEXT.md)、[架构决策](adr/)。
+- 工程 skills：[Issue 跟踪](agents/issue-tracker.md)、[分类标签](agents/triage-labels.md)、[领域流程](agents/domain.md)。
-## 工程 skills
-
-- [Issue 跟踪](agents/issue-tracker.md)：本仓库 GitHub Issues、显式仓库选择和工作项协作。
-- [分类标签](agents/triage-labels.md)：五个默认 triage 角色与 GitHub 标签映射。
-- [领域文档流程](agents/domain.md)：单上下文词汇、ADR 阅读与冲突处理。
-
-`AGENTS.md` 保留工程约束和按任务读取的入口；skills 工作流维护在 `docs/agents/`。
-
-## 文档规则
-
-- 协议文档只描述当前版本；被删除的字段和历史兼容结构不重复收录。
-- 技术标识符、配置键、API 名称和线上协议值保留原文，其余说明使用中文。
-- 验收文档保留可复现矩阵，不累积候选包版本、临时进程号或一次性性能结果。
-- 主机测试、交叉编译、模拟器和虚拟网络不能替代对应物理平台证据。
-- 公共行为变化必须同时更新实现、测试和相关契约。
+配置字段由 `config.yaml` 维护；协议文档补充语义与限制，不复制阶段计划。
+技术标识符保留原文，说明使用中文。AGENTS.md 只放跨任务约束与读取入口。
diff --git a/docs/acceptance.md b/docs/acceptance.md
index d6d0cd7..237b652 100644
--- a/docs/acceptance.md
+++ b/docs/acceptance.md
@@ -1,146 +1,62 @@
-# VCore 验收矩阵
+# 验证范围与发布边界
-本文记录验证范围与发布门禁，不把历史开发包结果当作当前 release 保证。
-源码 revision、lockfile/产物 hash、签名、环境、命令和结果保存在当次 PR 或发布记录中。
+测试入口见 [tests](../tests/README.md)，命令见 [scripts](../scripts/README.md)。
+本文定义证据边界，不是随源码自动续期的“全部通过”证明。
-## 证据规则
+## 必须保留的验证
-- 主机测试、交叉编译、模拟器和虚拟网络不能替代对应物理 TUN 或安装包证据。
-- x64 模拟不能替代原生 x64；VPN 双栈接口不能替代真实物理 IPv6。
-- 外网吞吐与进程间通信基准各自独立，不能相互替代。
-- 未执行或缺少可复现记录的项目保持未验证；不从旧产物继承通过结论。
-- 记录不得包含 secret、UUID、密钥、完整用户配置或私有目标信息。
-
-## 自动化覆盖
-
-当前 source/tests 覆盖：
-
-- Invoke API v5、单实例生命周期、Debug/Release 运行时线程重入拒绝、panic 与同步清理；
-- schema revision 14、IPv6、严格 YAML、节点 / `select` 组上游混合 DAG 和 node-only 测速；
-- 组上游与路由的共享选择、SOCKS5 UDP 建链快照、潜在 DIRECT 首跳准备、独立下载端点和深图回收；
-- HTTP 本机 / 认证共享、双栈监听回滚、逐请求认证与分发、Keep-Alive / 正文定界、CONNECT / Upgrade、10 MiB 双向摘要与活动连接 Stop；
-- SOCKS5 入站认证、三类目标、半关闭、TCP 授权 UDP、源端口学习/隔离、IPv6 作用域固定端口/学习端口匹配与跨接口隔离、过期/满队列/慢上游取消及纯 SOCKS5 Controller（作用域匹配为合成地址测试，不代表物理 LAN 验证）；
-- VLESS/XHTTP/TLS/REALITY、SOCKS5、AnyTLS、代理链、DNS、规则、GeoData 和 HTTP/TLS/QUIC 嗅探；
-- AnyTLS 有序 ALPN、WebPKI / 跳过 / 叶与非叶 pin、TLS 1.2/1.3 伪造签名拒绝、节点间策略隔离和精确恢复票据预算；
-- SS 2022 三算法白名单、同库 TCP/UDP 回环、有界 TCP 首写、首次传输前半关闭及 Pending 空握手续写、响应时间/认证/请求盐、UDP Pending/取消、重放/乱序/会话轮换、封装上限与来源检查，socket protect 失败关闭；
-- ICMPv4/v6、校验和、分片、MTU、队列与 Apple/Android 帧/fd/protect 所有权；
-- Windows 单 Application、token 绑定、Snapshot/profile、控制/数据协议、会合记录、
- 物理绑定、on-link prefix 去重、显式排除优先的路由和 MTU 派生的 UDP/DNS 上限；
-- Windows Job Object 进程监督，以及 Controller 鉴权、流量、实时组选择和有界请求。
-
-常规命令见 [README Validation](../README.md#validation)，平台构建与脚本检查见
-[scripts](../scripts/README.md)。运行时线程重入还需 Release 配置：
-
-```bash
-cargo test --locked --release --all-features --all-targets
-```
-
-后续外部互操作以 mihomo 为对端，不从单元测试推断：
-
-```bash
-bash tests/run_mihomo_interop.sh
-```
-
-该入口当前覆盖 8 个 HTTP 场景、8 个 SOCKS5 TCP/UDP 双向 IPv4/IPv6 场景及 17 个 AnyTLS 检查（12 个 TCP/UoT 数据场景、3 个独立测速、2 个证书拒绝）。版本、二进制 hash、超时及清理见 [scripts](../scripts/README.md#mihomo-协议互通)。既有 Xray / anytls-go 脚本保留为历史专用入口，未迁移的协议场景仍需补充 mihomo 证据，不能自动继承旧对端结果。
-
-## 协议与数据面
-
-| 能力 | 自动化 | 外部进程互操作 | 物理 TUN / 安装包 |
-| --- | --- | --- | --- |
-| VLESS + XHTTP + TLS/REALITY | 已覆盖 | mihomo stream-one/REALITY 有受控组合证据；其他模式仍待迁移；历史 Xray harness 保留 | Windows ARM64 开发包已覆盖 |
-| SOCKS5 CONNECT / UDP ASSOCIATE 出站 | 已覆盖 | mihomo TCP/UDP、IPv4/IPv6 | Windows ARM64 历史开发包已覆盖 |
-| SOCKS5 CONNECT / TCP 授权 UDP 入站 | 已覆盖 | mihomo 双向 TCP/UDP、IPv4/IPv6 | 真实 LAN / 物理 IPv6 未验证 |
-| AnyTLS TCP / UoT v2、ALPN / 证书策略 | 已覆盖 | mihomo 公开 YAML，TCP/UoT IPv4/IPv6、测速及证书拒绝 | 旧能力有 Windows ARM64 历史开发包记录；新 TLS 字段未做设备验证 |
-| SS 2022 | 三算法配置与 I/O/安全边界；活动 Stop、绑定失败回滚、独立测速和进程 FD 回收 | mihomo TCP/UDP × IPv4/IPv6/域名及服务器先发；具体/嵌套组/DIRECT 链；AES 1/2 层受控 EIH 中继 → mihomo；错误密钥/算法/身份拒绝 | 未验证 |
-| HTTP 本机 / 认证共享、消息定界与隧道 | 已覆盖 | mihomo 双向 harness（8 个场景） | 真实 LAN / 物理 IPv6 未验证 |
-| DIRECT 与代理链 | 已覆盖 | 本地 fixture | Windows ARM64 开发包已覆盖 |
-| DNS / rules / GeoData / sniffer | 已覆盖 | 本地 DNS 与代理 fixture | Windows ARM64 开发包已覆盖 |
-| ICMPv4 / ICMPv6 Echo | 已覆盖 | 不适用 | Windows ARM64 开发包已覆盖 |
-| Controller 四字段流量 | 已覆盖 | HTTP fixture | Windows ARM64 开发包已覆盖 |
-| Controller `select` 代理组控制 | 已覆盖 | HTTP fixture | 物理设备未验证 |
-| `dialer-proxy` 引用 `select` 组 | 配置、建链、切换与回收 fixture | 本地 SOCKS5 fixture | 物理设备未验证 |
-
-Windows 开发包的适用环境与证据入口见下节。本地互操作只证明受控配置，
-不代表所有公网服务、所有协议组合或当前发布包。
-
-2026-09-17 的 SS 候选在 macOS arm64 / Rust 1.98.1 上完成 12 项 SS 专项、Debug/Release 各 563 项库测试与 4 项兼容测试、17 项 netstack 测试及 clippy/依赖审计。默认构建、精简 feature 组合、Rust 1.91 检查和无 `interop-test` 的原生 macOS Release `ffi` 构建通过。mihomo 对端为 `ab405bad5beeeac8b003bb01f60f134f6df54471`，二进制 SHA-256 `99462761f951b08df9911cf82f96e2f0cf34cda959b1bc391584b1b1bb2de5b3`；当次三算法 Stop/回滚/测速后测试进程 FD 回到 6 的基线。
-
-SS 原样上游库的 padding 未初始化风险仍存在，未将相关失败证据改记为 PASS；完整说明见 [Shadowsocks](shadowsocks.md)。EIH 中继只处理身份头，最终 SS 业务解密由 mihomo 完成，不是同库自测或 mihomo 原生 EIH 服务端。
-
-跨协议候选增加四类出站的两跳 TCP/UDP、真实嵌套组切换、HTTP-only Controller / 测速快照、合成 utun 和 100 次生命周期检查。首次 1800 秒持续测试约 8 分半后因 UDP 来源异常失败；macOS 双栈 UDP 本地端口串扰已独立复现，但当时未保存完整 socket 映射，不把所有历史超时归为同一根因。随后仅在自有测试中增加双地址族端口保护与跨进程互斥，不修改 VCore 生产 socket 行为或第三方源码。修复后 Debug/Release 各 564 项库测试、4 项兼容测试和 2 项端口保护测试通过，lib/bins 及 mihomo fixture clippy 通过。
-
-修复后的单次 1800 秒长测通过：16 TCP + 16 UDP、1,754 次切组、29 次断连重建、470,248,320 字节校验；FD 为 6 → 195 → 6（含 32 个测试 guard），活动起始/峰值/结束/Stop 后 RSS 分别为 17,616 / 18,688 / 17,264 / 17,120 KiB，32-flow 建立耗时起始 165 ms、末次 166 ms。此结果不等于完整阶段签收：随后新增的 100 次快速重建检查两次失败，一次是收到 origin 请求后的回包超时，另一次在第 11 轮捕获 mihomo 的 `reject loopback connection`，AnyTLS 来源端口与该进程另一 UDP socket 端口同号。后一次有日志与 socket 映射佐证，前一次不强行归因。没有关闭 mihomo 保护或修改第三方；这些失败保留，不因独立网络重跑而改为 PASS。命令及限制见 [mihomo harness](../scripts/README.md#mihomo-协议互通)。
-
-随后配置 Apple Container 1.4.1 的专用 host-only 网络：首跳和末跳使用两个 Linux ARM64 mihomo，仍为相同源码 revision，Linux 程序 SHA-256 `eb35562be501dd6cd9e1f8bdf3ba43162bf6abb6a3946cd1f1ec0511462feab2`。反向 HTTP/SOCKS5 入站仍为原生对端，VCore 不开放 LAN。基础 IPv4/IPv6 互通、全部跨协议与宿主组合、100 次生命周期，以及 100 次快速 32-flow 重建通过；快速重建后 FD 回到 6，在用堆 64,176 B。最初适配中的固定回环断言和 SLAAC 地址未就绪失败分别保留并修正于自有测试。候选 Debug/Release 各 564 lib + 4 compatibility + 2 fixture、netstack 17、Python 18、clippy、feature 组合与依赖审计通过。
-
-该容器候选完成新的 1800 秒长测，完整测试总时长 1840.10 秒：16 TCP + 16 UDP、1,734 次切组、29 次断连重建、420,476,672 字节校验；FD 6 → 195 → 6。RSS 活动初始 / 峰值 / 结束 / Stop 后分别为 19,248 / 21,984 / 19,184 / 18,896 KiB；四次仅统计、不读取内容的堆采样约 4.90–4.91 MB，未出现持续活对象增长，后段 RSS 回落。初次 / 末次 32-flow 建立耗时为 204 / 153 ms；诊断采样扰动使最大 wave 达 441 ms，不能拿本轮的节流速率或最大延迟当无扰动性能基准。本机受控组合与资源门槛签收，全部自建对端与临时配置清理；这不修复或取消旧 macOS 同内核失败，不代表物理 TUN、LAN、IPv6 或平台发布门禁通过。
-
-## Apple 与 Android
-
-主机自动化覆盖 utun/rawIp、nonblocking、借用 fd 复制/关闭、EOF/非法包/部分写入、
-Android protect 失败关闭和重复 prepare/start/stop。构建脚本可生成 Apple
-XCFramework 与 Android arm64-v8a/x86_64 库。
-
-2026-09-17 在 `926e15b5070316763c82ed8d749580d811e61ddb` 的干净检出、无相邻 rustls 工作目录下，Apple 五目标（iOS arm64、simulator arm64/x86_64、macOS arm64/x86_64）和 Android 两 ABI 的标准 Release 构建通过。环境为 macOS 27 / arm64、Rust 1.98.1、Xcode 27.0（27A266a）及 SDK 27、Android NDK 28.2.13676358 / API 24。所有产物身份为 Invoke API v5 / schema 14，不含 `interop-test`；lockfile SHA-256 为 `64866bfff397559e3b5e9cb03094cfb229ccaf28ae2c8fae0a549d3a9106f8e2`。使用完整显式协议 feature 列表重建后，产物哈希与原 `ffi` / `tun` 传递启用方式一致。
-
-macOS ARM64 原生 C 宿主链接该 XCFramework，1,000 次 `version` Invoke / VCoreFree 和身份检查通过；这是 C ABI 冒烟，不是物理 TUN、完整应用或 x64 原生运行验证。新增 CI 构建矩阵仅通过本地静态检查，本轮未触发远端 CI，也未获得 Windows 新能力构建或设备数据面证据。
-
-同一干净检出的 locked fetch、C header、TLS/AWS-LC 来源审计及 Debug/Release 全测试通过（各 564 lib + 4 compatibility + 2 fixture，ignored 不计通过）。本机复用 Cargo cache，不声称验证了空缓存或离线下载。
-
-仍需独立验证：
-
-- Release iOS 无 debugger 的完整 TUN 生命周期与整进程内存轨迹；
-- Android 真机的 TUN、protect、DNS、TCP/UDP 和重复启停；
-- macOS system extension 的产品安装与生命周期。
-
-## Windows VPN
-
-### 已记录的开发环境
-
-Windows 11 ARM64 开发签名包曾覆盖数据面、生命周期、压力与有界 batching；
-单 Application loose-package 和后续 clean-install policy 门禁在 build 26200.9278
-执行。不同记录不能拼接成一份完整正式发布结论。
-
-| 记录 | 已观察范围 | 限制 |
+| 层次 | 验证内容 | 不能证明 |
| --- | --- | --- |
-| 单 Application Gate 0 | AppContainer Provider、无参数激活同包 medium-integrity Session Host、connect/stop、会合清理 | loose-package spike 的基线含未提交目标改动，单独基线 SHA 不能复现；不证明签名包或 Store |
-| 全局 policy / IPv4-only clean gate（2026-09-01） | IPv4-only/dual-stack lifecycle、LAN allow/block、IPv4 exclusion/control、Always On、cold profile、失败关闭和 Stop 后清理 | 只验证一个局域网 peer，没有逐个探测全部 on-link prefix |
-| PR 修复后同机开发包回归 | TCP、UDP、ICMPv4/v6，DNS 开关两种情况下的清缓存 hostname 请求、link-local route inventory、零残留 | 没有物理 IPv6/default gateway；UDP probe 仅验证正常大小报文，不证明超限传输 |
+| 离线 / 纯内存 | 严格配置与 feature、DAG/组快照、协议向量、TLS 身份/签名/pin、取消与局部上限、FFI 所有权 | 网络互通、设备 |
+| 容器互通 | 公开配置和消费者、真实认证及负例、传输关闭、UDP 来源与边界、受控 DNS/上游 | 任意字段组合或公网服务 |
+| 集成 / 压力 | 七出站的有序两跳、运行时切组、Stop/回滚/测速、重建、持续流量与静默窗口 | 无扰动吞吐基准或整机内存保证 |
+| 平台构建 / ABI | 同一锁文件、产物架构/身份/hash、原生 C/Swift 消费者与打包依赖 | 物理 TUN、签名安装 |
+| 设备 / 发布 | 真机网络、protect/物理绑定、正式宿主生命周期、签名安装及商店门禁 | 其他平台或后续 revision |
-门禁结束时检查 Session Host、VPN route/interface 和测试进程清理；已停止 Provider
-的 AppContainer 外壳可能暂留，原 case 之间显式清理它。Windows 的两条 `/1`、
-null IPv6 地址参数、物理 transport 绑定等实现约束见
-[Windows VPN](windows-vpn.md)，不在验收文档另维护一份。
+保留独立 ClientHello golden、Encryption 密码向量、H2 完整响应后 RST、SS 背压/读先于写的刷新、
+HY2 已完成分片 ID 重用等确定性回归。单纯复用实现生成期望值、声明字段数量或找到 PASS
+文本，不能替代行为验证。ignored、未运行、基础设施失败和清理失败均不得计为通过。
-### 不可变证据入口
+## 对端与已知限制
-以下记录保留环境、命令、结果和适用范围，替代滚动追加候选包叙述：
+- 所有协议端、原站、DNS 和提供入口的对照客户端遵守[隔离规则](testing-isolation.md)。
+ 优先 Mihomo listener；缺少的能力由官方 Xray、V2Ray、Hysteria 或 Shadowsocks 服务端补验。
+- 关闭行为按 Mihomo 的实际传输包装链验证；不要求所有传输在上传 EOF 后仍收到尾包。
+- WS + REALITY 的数据/认证对 Mihomo listener 验证；关闭使用同种 WS 的标准 TLS 分层参照。
+ 无指纹 JLS/gRPC、Safari ECH/gRPC 的官方对照缺口使用明确标注的 Chrome 关闭参照。
+ 这些不是完全同配置的客户端差分。
+- XHTTP H3/mTLS 使用获准的 Caddy 网关；packetaddr/sing-mux 等分层拓扑明确标注
+ 网关、会话处理器和解码端，不能宣称单个原生服务端直接支持全部能力。
+- 官方 Hysteria 回包缓冲包含协议头；V2Ray 部分 VMess 返回路径也有更小缓冲。
+ 原生夹具上限不改变 VCore 的协议预算。
+- SS 原样上游 padding 未初始化风险及空首包随机零 padding 被严格服务端拒绝的限制
+ 仍未修补。codec 级刷新回归不证明 server-first 互通。官方 ssserver 单层 EIH 终结与自有
+ 1/2 层身份中继是不同证据，不能据此宣称任意多层原生 EIH。详见[出站](outbounds.md#shadowsocks-2022)。
+- 静态 ECH、JLS、Encryption 与混合 REALITY 是选定能力集；动态 ECH、Restls、
+ ShadowTLS、WireGuard 不在当前范围。JLS 内部使用 fork hook 不构成 ShadowTLS 支持。
-- [Session Runtime lifecycle、失败关闭、重连与 pressure](https://github.com/OneVCore/VCore/blob/f41610c/docs/acceptance.md#windows-session-runtime-phase-6-2026-08-24)
-- [protocol-v1 有界 batching](https://github.com/OneVCore/VCore/blob/7856bef/docs/acceptance.md#windows-session-runtime-phase-6-2026-08-24)
-- [外部 TUN/DNS 地址与安装包边界](https://github.com/OneVCore/VCore/blob/1011955/docs/acceptance.md#6-windows-vpn)
-- [external Xray SOCKS tun2socks demo](https://github.com/OneVCore/VCore/blob/6636bd7/docs/acceptance.md#67-external-xray-socks-tun2socks-demo)
-- [UWP VPN 最小示例 lifecycle](https://github.com/OneVCore/VCore/blob/26e1095/docs/acceptance.md#windows-vpn)
-- [单 Application spike 与 2026-09-01 policy/data-plane gate 完整记录](https://github.com/OneVCore/VCore/blob/9205e2e83dc84905f24a7dda5570582d71d075b5/docs/acceptance.md#windows-vpn)
+## 当前证据如何使用
-### 未完成发布门禁
+精简前的[冻结验收索引](https://github.com/OneXray/VCore/blob/b7c0100602e188bf28b9fa5370e11120069b54f7/docs/acceptance.md)
+保留各次运行、原始失败、环境和适用 revision；[完整阶段记录](https://github.com/OneXray/VCore/tree/b7c0100602e188bf28b9fa5370e11120069b54f7/docs/acceptance)
+可在 Git 历史查阅。它们不再复制到当前文档。
-- production-signed MSIX、WACK、Partner Center identity/publisher 与受限能力审批、
- ARM64/x64 Store bundle、提交与安装路径；
-- Windows 10 20H2、原生 x64、真实物理 IPv6、新鲜物理网卡禁用场景；
-- 多用户和远程会话；
-- 带公开可复现命令的 `sessionBackend` package-boundary argv、进程退出和 Job
- 清理矩阵，以及 native x64/正式宿主 UI 路径回归。
+该基线记录过本地协议集成、持续压力与 Apple/Android 构建通过；随后 boring release /
+Shadowsocks registry 接入只做了定向 JLS、SS 和离线回归，没有重签全部组合及长测。
+平台交付仍未完整签收。这些是历史记录范围，不代表当前 checkout、远端 CI 或发布候选
+已经重新执行。后续结果放当次 PR、CI artifact 或发布记录，绑定源码、锁文件、对端、
+命令、结果及清理证据，不在本文累计包哈希和阶段流水账。
-## rustls REALITY 发布
+## 尚需独立签收
-REALITY 线上向量、普通 TLS、错误 key/short ID、HRR、并发和取消有自动化覆盖。
-正式发布仍需：
+- iOS 无 debugger 的 Release TUN 生命周期与整进程内存；Android 真机 TUN/protect、
+ DNS/TCP/UDP、重复启停；macOS system extension 正式宿主安装和生命周期。
+- Windows 10 20H2、原生 x64、真实物理 IPv6、物理网卡禁用、多用户/远程会话；
+ session backend 包路径/argv/退出与 Job 清理、正式宿主 UI。
+- production-signed MSIX、WACK、Partner Center identity/publisher 与受限能力、
+ ARM64/x64 Store bundle、提交及安装。
+- 干净 checkout、同一 lockfile 的平台产物、原生运行库和完整许可证审查。
-- 无相邻 rustls 目录的干净检出执行 locked tests；
-- 使用同一 lockfile 完成 Apple、Android、Windows 构建；
-- 保存 VCore/rustls revision、toolchain、目标架构、lockfile/产物 SHA-256、
- 签名安装与当次物理设备/网络/失败关闭矩阵。
-
-详细要求见 [rustls 发布契约](rustls-reality-release.md)。
-没有当次证据的项目不得写成发布保证。
+Windows 11 ARM64 历史开发包曾覆盖数据面、policy 和生命周期；loose-package、
+单个 LAN peer、合成 utun 或交叉编译均不能抵扣上述门禁。记录遵守隐私规则，不含
+真实凭据、UUID、密钥、完整用户配置或私有目标。
diff --git a/docs/adr/0003-run-windows-runtime-in-a-full-trust-session-host.md b/docs/adr/0003-run-windows-runtime-in-a-full-trust-session-host.md
index cebc736..26fe64d 100644
--- a/docs/adr/0003-run-windows-runtime-in-a-full-trust-session-host.md
+++ b/docs/adr/0003-run-windows-runtime-in-a-full-trust-session-host.md
@@ -8,4 +8,4 @@ AppContainer Provider 只拥有 `VpnChannel`、包缓冲区、路由、物理网
Session Host 通过 `IApplicationActivationManager` 激活，并使用 Provider 发布的 AppContainer 限定对象路径连接控制管道和数据管道。会合记录只包含协议版本、快照令牌、相对对象路径和固定管道名称。
-该拆分使 Controller 和本机 SOCKS5 服务可由完全信任进程正常访问，同时不引入 Wintun、`CheckNetIsolation` 豁免、宽泛 DACL 或按协议转发层。完整契约见 [Windows 会话运行时](../windows-session-runtime.md)。
+该拆分使 Controller 和本机 SOCKS5 服务可由完全信任进程正常访问，同时不引入 Wintun、`CheckNetIsolation` 豁免、宽泛 DACL 或按协议转发层。完整契约见 [Windows 会话运行时](../windows-vpn.md)。
diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md
index ef9529a..b09550f 100644
--- a/docs/agents/issue-tracker.md
+++ b/docs/agents/issue-tracker.md
@@ -1,19 +1,19 @@
# Issue tracker: GitHub
-Issues and specs live in GitHub Issues for `OneVCore/VCore`.
+Issues and specs live in GitHub Issues for `OneXray/VCore`.
-Use `gh`. Every issue or PR command must specify `--repo OneVCore/VCore` because
-the SSH remote uses an alias. For `gh api`, use an explicit `repos/OneVCore/VCore/...`
-endpoint.
+Use `gh`. Every issue or PR command must specify `--repo OneXray/VCore`.
+For `gh api`, use an explicit `repos/OneXray/VCore/...` endpoint. Before publishing,
+verify that `origin` and the resolved GitHub repository still identify this project.
## Operations
-- Publish a request/spec: `gh issue create --repo OneVCore/VCore --title "..." --body-file `.
-- Read a ticket: `gh issue view --repo OneVCore/VCore --comments`.
-- List tickets: `gh issue list --repo OneVCore/VCore --state open --json number,title,body,labels,comments`.
-- Comment: `gh issue comment --repo OneVCore/VCore --body-file `.
-- Apply/remove labels: `gh issue edit --repo OneVCore/VCore --add-label "..."` / `--remove-label "..."`.
-- Close: `gh issue close --repo OneVCore/VCore --comment "..."`.
+- Publish a request/spec: `gh issue create --repo OneXray/VCore --title "..." --body-file `.
+- Read a ticket: `gh issue view --repo OneXray/VCore --comments`.
+- List tickets: `gh issue list --repo OneXray/VCore --state open --json number,title,body,labels,comments`.
+- Comment: `gh issue comment --repo OneXray/VCore --body-file `.
+- Apply/remove labels: `gh issue edit --repo OneXray/VCore --add-label "..."` / `--remove-label "..."`.
+- Close: `gh issue close --repo OneXray/VCore --comment "..."`.
Read a referenced ticket's body, comments, and labels before acting on it.
Use the [label mappings](triage-labels.md) for canonical triage roles.
@@ -36,6 +36,6 @@ Issues hold requests and specs; PRs hold implementation changes.
`Blocked by: #` in the child and inspect those issues' states.
- A child is unblocked only when every blocker is closed.
- Select the first open, unassigned, unblocked child in map order.
-- Claim it with `gh issue edit --repo OneVCore/VCore --add-assignee @me`.
+- Claim it with `gh issue edit --repo OneXray/VCore --add-assignee @me`.
- Resolve by commenting the result, closing the ticket, and appending
a concise result and evidence link to the map's Decisions-so-far.
diff --git a/docs/anytls.md b/docs/anytls.md
deleted file mode 100644
index ce2cd2a..0000000
--- a/docs/anytls.md
+++ /dev/null
@@ -1,111 +0,0 @@
-# AnyTLS 出站
-
-本文描述当前 AnyTLS 客户端出站契约。VCore 支持 AnyTLS v2、兼容 v1 的会话、内置填充和 UoT v2。
-
-## 配置
-
-```yaml
-proxies:
- - name: anytls-edge
- type: anytls
- server: anytls.example.com
- port: 443
- password: "private-password"
- sni: origin.example.com
- # alpn: [h2, http/1.1]
- skip-cert-verify: false
- # fingerprint: ""
- udp: true
- # dialer-proxy: socks-hop
-rules:
- - MATCH,anytls-edge
-```
-
-- `name`、`type`、`server`、`port` 和 `password` 必填，`type` 固定为 `anytls`。
-- `password` 长度为 1–1024 个 UTF-8 字节，不得出现在调试输出、日志或错误正文中。
-- `sni` 可省略，默认使用 `server`；两者都必须是合法 IP 字面量或域名。
-- `alpn` 可省略或为 `[]`，均不发送 ALPN；非空列表按配置顺序发送。每项为 1–255 个 UTF-8 字节，带长度字节的列表总长最多 65,533 字节。
-- `skip-cert-verify` 默认为 `false`；`fingerprint` 为证书 DER 的 SHA-256，接受大小写十六进制及冒号分隔形式，去除冒号后必须为 64 个十六进制字符。
-- `udp` 默认为 `false`；设为 `true` 后启用 UoT v2。
-- `dialer-proxy` 使用与其他出站相同的无环代理图。
-- 未列出的字段一律拒绝。TLS 版本、客户端伪造指纹、ECH、mTLS、填充和会话参数不可配置。
-
-## TLS 与认证
-
-AnyTLS 使用 VCore 的标准 TLS 客户端：
-
-- 支持 TLS 1.3 和 TLS 1.2；
-- 默认使用 WebPKI 根证书、规范化 SNI 和完整证书校验；
-- `skip-cert-verify: true` 且没有 pin 时跳过常规证书链、名称及有效期验证；
-- `fingerprint` 匹配叶证书时，以该证书作为信任依据，不再要求公共根、名称或有效期匹配；匹配非叶证书时，以它为信任锚，继续验证叶证书链、名称及有效期；
-- 配置了 pin 却不匹配时必须失败，`skip-cert-verify` 不能覆盖 pin；
-- 所有策略始终验证 TLS 握手签名，跳过常规校验并不等于接受伪造签名；
-- ALPN 按配置发送，不强制服务端选中某一协议；
-- 不支持 REALITY、客户端伪造指纹、ECH 或客户端证书。
-
-校验策略、SNI、ALPN 和恢复缓存属于各节点不可变的 TLS 客户端，不跨节点共享。恢复票据按节点分配固定额度，运行时标准 TLS 总预算仍为 4；TLS 1.3 票据一次性消费，TLS 1.2 会话也占用同一额度。VLESS 的 TLS 1.3 / h2 / WebPKI 要求和 REALITY 的禁用恢复策略不受 AnyTLS 配置影响。
-
-连接建立后，客户端依次写入 SHA-256 password hash、认证填充和首个会话批次。认证材料不得进入日志或错误信息。
-
-## 版本协商
-
-客户端首个 `Settings` 固定声明 `v=2`，并携带当前填充方案的 MD5，不附带产品或客户端版本标识。服务端返回合法的 `ServerSettings v>=2` 时按 v2 工作；未返回时按兼容 v1 的方式继续。
-
-首个流与认证批次一同发送。复用空闲会话时：
-
-- v2 会话写出 `SYN` 和目标后立即返回可用流，并启动最长 3 秒的 `SYNACK` 监视任务；
-- 兼容 v1 的会话不等待 `SYNACK`；
-- 非空 `SYNACK` 负载表示拒绝，整个物理会话随即失败；已经返回的流通过后续 I/O 暴露错误；
-- `SYNACK` 超时、读写器关闭或协议错误都会销毁物理会话；
-- 只有在 `open` 返回前发现空闲会话已经失效时，当前请求才允许新建一次物理连接。返回后的失败不会静默重拨。
-
-未知流、错误控制流 ID、方向错误的帧、越界负载和非法 `ServerSettings` 都是会话级错误。远端诊断最多保留 256 字节。
-
-## TCP 会话复用
-
-- 一个物理会话同时只承载一个活动流。
-- 流完整结束后，物理会话才进入空闲列表。
-- 新请求优先复用序号最大的空闲会话。
-- 空闲检查周期和超时均为 30 秒，不预热连接。
-- 空闲清理任务在节点首次使用时按需启动；只构建未使用的节点不创建后台任务，建图或监听绑定失败不会遗留空闲 worker。
-- 活动物理会话不设固定业务数量上限。
-- 流 ID、会话序号耗尽或状态不一致时立即关闭对应会话。
-
-写命令通道容量为 2。每个流的接收通道由运行时缓冲区容量推导且至少为 1。帧、填充、队列和诊断字符串都受固定上限约束，这些上限不开放为 YAML 参数。
-
-## UDP over TCP
-
-`udp: true` 时使用 UoT v2 目标：
-
-```text
-sp.v2.udp-over-tcp.arpa:0
-```
-
-UoT 固定采用数据报模式。首包携带 UoT 请求和第一份数据报，后续数据报各自编码 IPv4、IPv6 或域名目标，因此同一关联可以访问不同目标。协议帧负载最多 65,535 字节，同时继续受调用方给出的最终响应负载上限约束。
-
-响应通道容量为 1。关闭、取消或丢弃 UoT 传输时，读取任务和底层流必须一起结束。
-
-## 填充
-
-客户端内置固定填充方案，不提供 YAML 配置。每个新物理会话取得一份不可变快照；服务端的合法 `UpdatePaddingScheme` 只影响之后创建的会话，不改变当前帧边界。非法更新只产生有界警告。
-
-填充文本、每包条目数、停止值、逻辑填充量和帧负载均有固定上限。认证填充和后续数据填充使用同一份会话快照。
-
-## 生命周期
-
-每个运行时代理图为 AnyTLS 节点创建一个共享客户端和显式生命周期句柄：
-
-```text
-准备代理图
- -> 启动
- -> 按需打开 TCP/UoT 流
- -> begin_shutdown
- -> shutdown().await
- -> 释放代理图
-```
-
-`begin_shutdown` 是同步第一阶段屏障：禁止新流、清空空闲列表、取消客户端令牌并通知所有会话关闭。`shutdown` 随后等待空闲清理、会话读写器和 UoT 任务全部结束。运行时停止、准备回滚、测速工作器释放和失败清理必须使用同一路径。
-
-AnyTLS 状态只属于创建它的运行时或测速工作器，不跨运行时共享。`measureDelay` 返回前必须完成私有代理图的关闭。
-
-自动化和外部互操作的实际覆盖范围见 [验收矩阵](acceptance.md)。
diff --git a/docs/config.yaml b/docs/config.yaml
index 89c64b9..f0f8e6a 100644
--- a/docs/config.yaml
+++ b/docs/config.yaml
@@ -1,6 +1,6 @@
-# VCore 配置修订版 14 的完整示例。
+# VCore 配置修订版 27 的完整示例。
#
-# `version.configVersion` 返回的 14 是二进制报告值，不是 YAML 字段。配置只接受
+# `version.configVersion` 返回的 27 是二进制报告值，不是 YAML 字段。配置只接受
# 本文列出的结构；未知字段、anchor、alias 和自定义 tag 都会失败。
#
# 宿主先通过 Invoke API v5 调用 initialize({dataDir})，再通过 configYaml 内联
@@ -29,10 +29,10 @@ geo-update-interval: 24
# 按首个冒号分隔，用户名 / 密码各 1–255 UTF-8 字节，HTTP/SOCKS5 共用。
# 共享或非空认证要求 port 或 socks-port 启用。
# HTTP 逐请求认证、选路，支持流式正文 / 分块、Keep-Alive、CONNECT 与 Upgrade。
-# 共享只适合可信网络，Basic 不加密链路；详细边界见 docs/http-proxy.md。
+# 共享只适合可信网络，Basic 不加密链路；详细边界见 docs/inbounds.md#http。
port: 1080
# SOCKS5 CONNECT / UDP ASSOCIATE；省略或 0 关闭，非零时 TCP/UDP 同端口。
-# UDP 必须属于有效的 TCP 控制连接，源 IP/端口校验和资源上限见 socks5-proxy.md。
+# UDP 必须属于有效的 TCP 控制连接，源 IP/端口校验和资源上限见 inbounds.md#socks5。
socks-port: 1081
allow-lan: false
authentication:
@@ -80,30 +80,146 @@ sniffer:
# 范围内的 IPv4 字面量或 ::1；域名解析到回环地址会失败关闭。
#
# VLESS 子集：
-# - type 固定 vless，network 固定 xhttp，tls 必须为 true；
-# - encryption 省略或 none，flow 省略或空字符串；
-# - servername 可省略（缺省为 server），alpn 省略或严格 [h2]；
+# - type 固定 vless，network 默认 tcp，支持 tcp/ws/grpc/http/h2/xhttp，tls 默认 false；
+# TCP 支持明文或 TLS 1.2/1.3；XHTTP H1/H2 支持明文、TLS1.3 或 REALITY。
+# - encryption 省略/空/none，或 mlkem768x25519plus.{native,xorpub,random}.{1rtt,0rtt}.…；
+# key/padding 链、上限和恢复规则见 vless.md；该层独立于外层 TLS/传输。
+# flow 省略/空/xtls-rprx-vision；Vision 仅 TCP + TLS1.3/REALITY 或 Encryption，
+# packet-encoding 必须 xudp（即使 udp=false）；
+# - servername 可省略（WS Host 去端口后优先于 server）；TCP alpn 默认空，
+# WS 默认 [http/1.1]，gRPC/H2 默认 [h2]；XHTTP [http/1.1] 选择 H1，
+# 空或 H1/H2 列表选择 H2，仅 [h3] 选择 H3。H3 必须标准 TLS1.3 与受控 UDP，
+# 不回退 H2。明文 XHTTP 的 alpn 仅选择版本，其余 TLS 专属字段仍拒绝。
+# 详细语义见 docs/vless.md 和 docs/xhttp.md。
+# - packet-encoding 默认 xudp；none 是显式 raw，packetaddr/packet 为 IP-only
+# 地址帧。raw 固定首包目标；packetaddr 域名通过受控 DNS 解析。
# - TLS 省略 reality-opts；REALITY 必须提供 reality-opts.public-key，可选 short-id；
-# - xhttp-opts 可包含 host/path/mode/download-settings，mode 只接受
+# support-x25519mlkem768 默认 false；true 强制真实混合协商、不回退经典组。
+# true 只允许 client-fingerprint chrome 或未命名（省略/none/空串）；不改写模板。
+# - xhttp-opts 请求字段与值域详见 docs/xhttp.md；mode 只接受
# auto/packet-up/stream-up/stream-one；stream-one 不能与 download-settings 同用；
# - download-settings 一旦出现（包括 {}），就为下行 GET 创建独立的
-# server -> TLS/REALITY -> HTTP/2 连接；上行 POST 仍走主连接，两者共用
+# 独立传输/安全连接；上行 POST 仍走主连接，两者共用
# XHTTP session ID，不进行第二次 VLESS 握手。两条请求最终必须由 CDN 或
-# 反向代理汇聚到同一个服务端 XHTTP 处理器和会话存储。只支持
-# server/port/tls/servername/alpn/reality-opts/host/path；
-# - download-settings 中缺省的字段继承主连接。reality-opts 缺省时继承
-# 主连接的 TLS/REALITY，即外层 REALITY 下单独写 tls: true 也不会清除
-# REALITY；reality-opts 存在时选择/覆盖 REALITY，tls: false 始终失败。
-# 当前结构没有“清除已继承 REALITY”的标记，因此无法表达“主连接 REALITY、
-# 下行连接标准 TLS”；解析器不会猜测该语义。
+# 反向代理汇聚到同一个服务端 XHTTP 处理器和会话存储。
+# - download-settings 缺省叶字段继承；headers/reuse-settings/reality-opts/jls-opts/ech-opts 整对象
+# 替换，{} 分别清空请求头、重置复用默认、清除 REALITY/JLS/ECH。false/空串不等同缺省；
+# certificate/private-key 成对替换或同时空串清除。改变安全类型须显式清除冲突
+# 策略。两个独立 listener 不能组成共享会话。
# auto 为 TLS -> packet-up、REALITY +
# download-settings -> stream-up、REALITY 无 download-settings -> stream-one；
-# - 不接受 packet-encoding、headers/reuse-settings、fingerprint、client-fingerprint、
-# skip-cert-verify、ECH、mTLS、shadow-tls-opts、restls-opts 或 jls-opts。
+# - XHTTP 关闭语义与 Mihomo 一致：应用上传 EOF / shutdown 结束整条逻辑连接，
+# 同时关闭下载腿，不提供 TCP 半关闭后继续读取尾包的保证；packet-up 的待完成
+# 上传最多等待 1 秒。需要完整响应的应用须在关闭前读完响应。
+# - 标准 TLS 支持 skip-cert-verify/fingerprint/name-cert-verify，以及配对的
+# 内联 PEM certificate/private-key；不能混用 REALITY。完整策略见 vless.md。
+# - WS/gRPC/HTTP/H2 复用共享传输。WS 可 v2ray-http-upgrade 及其 fast-open；
+# gRPC 可 UA、空闲 PING、max-connections/min-streams/max-streams 池阈值。
+# - smux 支持 h2mux/smux/yamux、padding/only-tcp 与池阈值；与 Vision 互斥。
+# - client-fingerprint 接受 none/chrome/chrome120/firefox/firefox120/safari/safari16；
+# chrome=Chrome133，firefox=Firefox120，safari=Safari16.0；节点缺省关闭。
+# 适用于标准 TCP TLS/REALITY，不改变证书 fingerprint；下载腿缺省继承、
+# 显式名称覆盖、none/空串清除，转 H3/明文必须清除指纹。
+# 非空 ALPS 服务端设置暂拒绝；边界见 docs/tls-client-fingerprint.md。
+# - jls-opts.username/password 必须成对非空，各 1–65535 UTF-8 字节，要求 tls: true；
+# 与同腿 REALITY/证书策略/mTLS、Vision/H3 互斥。下载对象缺省继承、整体替换、
+# {} 清除，主腿空对象拒绝。保持完整 TLS1.3 认证，无恢复；详见 vless.md#jls。
+# - 静态 ech-opts 只用于标准 TLS，详见下方示意与 docs/vless.md#静态-ech。
+# 不接受动态 query-server-name、shadow-tls-opts 或已移除的 restls-opts。
#
# 下方 vless-edge 通过 upstream-select 当前选择的 socks-hop 建链：
# 客户端 -> socks-hop -> vless-edge -> 目标。
proxies:
+ # Hysteria2：固定 QUIC/TLS1.3，外层总是需要 UDP；业务 UDP 默认关闭。
+ # 完整字段/预算及开发验收边界见 outbounds.md#hysteria2。标准 TLS 证书策略与其他协议共用。
+ - name: hysteria2-edge
+ type: hysteria2
+ server: hysteria2.example.com
+ port: 443
+ password: "synthetic-hysteria2-password"
+ sni: hysteria2.example.com
+ alpn: [h3] # 缺省或 [] 都归一为 h3
+ skip-cert-verify: false
+ # fingerprint: ""
+ # certificate/private-key: 成对内联 PEM 客户端身份
+ udp: true
+ up: 0 # 裸数单位 Mbps；0 自动，也可 "125 KBps"，b=bit/B=byte
+ down: 0
+ udp-mtu: 1197 # 单个协议分片预算；0 同默认，范围 64–65535
+ # obfs: salamander
+ # obfs-password: "independent-synthetic-password"
+ # ports: "443,8443-8445" # 非空集合控制初始及后续入口；出现时 port 可省略
+ # hop-interval: "5-7" # 仅与 ports 配套，默认 30 秒，最小 5 秒
+ # dialer-proxy: upstream-select
+
+ # VMess AEAD：alterId 仅 0；cipher 默认 auto（实际 AES 硬件检测），还支持
+ # aes-128-gcm/chacha20-poly1305/none，zero 归一为 none。
+ # global-padding/authenticated-length 默认 false；none/zero 不接受 true。
+ # network 默认 tcp，支持 tcp/ws/grpc/http/h2。tls 默认 false；关闭时
+ # 禁止 servername/alpn/fingerprint/skip-cert-verify 等 TLS 专属字段。
+ # servername 优先显式值，其次 WS Host 去端口，否则 server。
+ # ws-opts/grpc-opts 与下面 Trojan 的结构相同；HTTP/H2 选项见示例注释。
+ # UDP 默认 false；packet-encoding 默认为空（raw），或 xudp/packetaddr。
+ # raw transport 固定首包目标；packetaddr 域名由受控 VCore DNS 解析为 IP。
+ # TCP/WS 保留下载侧；gRPC/HTTP/H2 上传 EOF 关闭逻辑流，详见 outbounds.md#vmess-aead。
+ - name: vmess-edge
+ type: vmess
+ server: vmess.example.com
+ port: 443
+ uuid: 00000000-0000-4000-8000-000000000002
+ alterId: 0
+ cipher: auto
+ network: tcp
+ tls: true
+ servername: vmess.example.com
+ udp: true
+ packet-encoding: xudp
+ global-padding: false
+ authenticated-length: false
+ # network: http
+ # http-opts:
+ # method: GET
+ # path: [/cover, /other] # 按 URL.Path 编码；缺省/空列表为 [/]
+ # headers: {Host: [cover.example:443], X-Custom: [one, two]}
+ # 每次握手各选一个路径与每个头的一个值；禁止 Content-Length/Transfer-Encoding。
+ # network: h2
+ # h2-opts:
+ # host: [cover.example:443] # 必填、非空；每流选一个，不改变 TLS 认证名
+ # path: /cover # 默认 /；普通 PUT body，不使用 gRPC framing
+
+ # Trojan（outbound-trojan feature）：固定 TLS，不接受 tls 开关。
+ # password 必须非空，按原始 UTF-8 字节认证，不 trim。
+ # network 接受 tcp（默认）、ws、grpc。sni 默认 server，不回退 WS Host；
+ # alpn 默认 tcp=[]、ws=[http/1.1]、grpc=[h2]。显式列表保留顺序，WS/gRPC
+ # 必须包含适用协议并校验实际协商结果。上传 EOF 保留下载侧，直到对端结束；
+ # Stop / 取消仍关闭全部会话及自有 driver，不更改 XHTTP 的全关闭约定。
+ # skip-cert-verify 默认 false；fingerprint 沿用 AnyTLS 的证书 SHA-256
+ # pin 语义，pin 与 skip 同时存在仍必须匹配 pin。udp 默认 false。
+ # UDP 在 TLS 流内传输；单包负载最多 8192 字节并与入口预算取较小值，
+ # 不拆包或截断。域名地址保持域名交由服务端处理；Mihomo v1.19.31 的
+ # Trojan listener 不接收域名 UDP 帧，使用该对端时需要 IP 业务目标。
+ - name: trojan-edge
+ type: trojan
+ server: trojan.example.com
+ port: 443
+ password: example-only-password
+ network: tcp
+ sni: trojan.example.com
+ udp: true
+ # network: ws
+ # ws-opts:
+ # path: /edge?query=1 # 默认 /，必须绝对路径
+ # headers: {Host: cover.example:443, X-Custom: value}
+ # max-early-data: 2048 # 0–2048，默认 0
+ # early-data-header-name: Sec-WebSocket-Protocol
+ # W04>0 时头名缺省为 Sec-WebSocket-Protocol；可显式自定义头，或空字符串
+ # 使用路径后缀（此时 path 不可含 query）。禁用 ED 时不接受无效的头名选项。
+ # 不接受保留握手头、重复大小写头、CR/LF、userinfo 或超限 HTTP 头。
+ # network: grpc
+ # grpc-opts:
+ # grpc-service-name: edge # 必填；普通名映射 /edge/Tun；/ 开头使用完整路径
+ # ws-opts / grpc-opts 仅可用于对应 network；不提供 gRPC 连接池。
+
- name: vless-edge
type: vless
server: edge.example.com
@@ -119,6 +235,18 @@ proxies:
host: edge.example.com
path: /onev
mode: auto
+ headers: {X-Transport: edge}
+ # 以下范围均为字符串 N 或 N-M。所有请求字段与合法配套见 docs/xhttp.md。
+ x-padding-bytes: "100-1000"
+ sc-max-each-post-bytes: "1000000" # packet-up，最多16MiB，非预分配大小
+ sc-min-posts-interval-ms: "30" # packet-up，0–60000且最大值为正
+ reuse-settings: # 省略无额外池；{} 启用默认池，阈值不是全节点数量上限
+ max-concurrency: "0"
+ max-connections: "0"
+ c-max-reuse-times: "0"
+ h-max-request-times: "0" # 按领取 transport，不按每 POST
+ h-max-reusable-secs: "0"
+ h-keep-alive-period: 0 # H2默认45秒/H3默认10秒；负数禁用；H1仅0
# 完整覆盖示例；改成 download-settings: {} 则所有字段继承主连接。
download-settings:
server: download.edge.example.com
@@ -127,7 +255,25 @@ proxies:
servername: download.edge.example.com
alpn: [h2]
host: download.edge.example.com
- path: /onev-download
+ path: /onev # 与主腿汇入同一原生 handler
+ headers: {} # 清除主腿自定义请求头
+ reuse-settings: {} # 整体重置，不按叶继承
+ skip-cert-verify: false
+ fingerprint: "" # 清除继承的 pin
+ client-fingerprint: "" # 清除继承的 ClientHello profile
+ name-cert-verify: "" # 恢复下载认证名
+ # certificate: # 与 private-key 成对；禁止文件路径
+ # private-key:
+ # reality-opts: {} # 清除继承的 REALITY；非空对象必须提供 public-key
+ # jls-opts: {} # 清除继承的 JLS；非空对象必须提供 username/password
+ smux:
+ enabled: false
+ protocol: h2mux # h2mux/smux/yamux
+ max-connections: 1 # 0–i32::MAX；正值与正 max-streams 互斥
+ min-streams: 0
+ max-streams: 0
+ padding: false
+ only-tcp: false # true 保留 packet-encoding；false 使用 sing-mux UDP
dialer-proxy: upstream-select
# REALITY 写法示意：在 VLESS 节点中保留 tls: true，并增加以下 mapping；不要与
@@ -135,6 +281,15 @@ proxies:
# reality-opts:
# public-key: BwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwc
# short-id: "0123"
+ # support-x25519mlkem768: false # 主腿/下载腿均可配置，必须为非 null 布尔值
+
+ # 标准 TLS 的可选静态 ECH；主腿与 download-settings 使用相同字段。
+ # 启用时 config 必填标准 Base64 ECHConfigList，不能只填写 enable。
+ # 实际只协商 TLS1.3，servername 必须是 DNS 名；不查询 DNS 或自动明文回落。
+ # {} 清除；不能与同腿 REALITY/JLS、Vision 混用，详细契约见 docs/vless.md#静态-ech。
+ # ech-opts:
+ # enable: true
+ # config: ""
# SOCKS5 出站支持 CONNECT 和 UDP ASSOCIATE。username/password 必须同时省略
# 或同时出现；tls 只能省略或为 false。udp 控制 UDP ASSOCIATE。
@@ -150,7 +305,7 @@ proxies:
# sni 省略时使用 server。TLS 1.3/1.2 默认 WebPKI，alpn 省略/[] 时不发送。
# skip-cert-verify 不能覆盖 fingerprint；pin 是证书 SHA-256，不是客户端伪造指纹。
# 叶 pin 直接决定信任；非叶 pin 作为根继续验证链和名称。所有策略均验证握手签名。
- # 不支持 REALITY、fp、ECH、mTLS 或 session/padding 调参字段，详见 anytls.md。
+ # 不支持 REALITY、fp、ECH、mTLS 或 session/padding 调参字段，详见 outbounds.md#anytls。
# TCP 使用 AnyTLS session；udp: true 使用 UoT v2 datagram mode。
- name: anytls-edge
type: anytls
@@ -161,6 +316,7 @@ proxies:
# alpn: [h2, http/1.1]
skip-cert-verify: false
# fingerprint: ""
+ # client-fingerprint: chrome # 可选；与上方证书 pin 独立
udp: true
# SS 2022：cipher 精确接受下列三种；AES-128 密钥解码后 16 字节，其余为 32。
@@ -168,7 +324,7 @@ proxies:
# 2022-blake3-chacha20-poly1305。
# AES password 可用 iPSK1:...:iPSKn:uPSK 身份链，其他算法仅单一 Base64 PSK。
# 以下仅为公开测试 key，不可用于真实服务。UDP 默认 false。
- # 上游 padding 风险和验收边界见 shadowsocks.md；
+ # 上游 padding 风险和验收边界见 outbounds.md#shadowsocks-2022；
# 完整互通尚未签收。dialer-proxy 可引用具体节点或 select 组。
- name: ss-edge
type: ss
@@ -196,7 +352,8 @@ proxies:
# 当前节点的服务器而不是业务目标，REJECT 在建链时失败且不回退。单次建链对每个组
# 只读一次选择，SOCKS5 UDP 控制流与 relay 路径共用该快照和期限；不同组没有原子
# 快照保证。复用旧 AnyTLS 会话的新业务流仍沿用该会话路径，只有新建底层 transport
-# 才读取新选择。业务节点的 udp 开关不阻止上游通过 TCP 承载封装后的 UDP。
+# 才读取新选择。已认证 Hysteria2 会话的新逻辑流和跳端口 socket 同样沿用初始上游
+# 快照，只有新建认证会话读取新选择。业务节点的 udp 开关不阻止上游通过 TCP 承载封装后的 UDP。
proxy-groups:
- name: upstream-select
type: select
diff --git a/docs/controller-api.md b/docs/controller-api.md
index 8ce7cb4..ec1f9f3 100644
--- a/docs/controller-api.md
+++ b/docs/controller-api.md
@@ -129,6 +129,8 @@ Content-Length: 26
`dialer-proxy` 与规则、DNS 共享同一组选择，但经共享连接器直接建链，不重新执行业务规则。上游组的 `DIRECT` 连接当前节点预解析的服务器，`REJECT` 使建链失败。单次建链对同一组只读取一次选择，SOCKS5 UDP 的控制连接和 relay 路径共享该快照；不同组之间不提供原子快照。已经读取旧选择的在途握手继续原路径。复用旧 AnyTLS 会话的新业务流也保留原路径，只有真正新建底层 transport 才读取新选择。
+Hysteria2 已认证 QUIC 会话也保留其 `dialer-proxy` 上游组快照，包括复用该会话的新业务流和端口跳跃所需的新物理 socket；这些不是新的认证会话，不能因切组而迁移原路径。只有重新建立的认证会话才读取新的上游组选择。节点本身作为路由组成员时，后续业务的路由选节点仍按当前组选择执行。
+
## HTTP 状态与协议边界
| 状态 | 含义 |
diff --git a/docs/http-proxy.md b/docs/http-proxy.md
deleted file mode 100644
index 7d33af1..0000000
--- a/docs/http-proxy.md
+++ /dev/null
@@ -1,59 +0,0 @@
-# HTTP 代理入站
-
-HTTP 入站通过当前 Session 的 Dispatcher 使用规则、节点和静态 `select` 代理组。实现位于 `src/inbound/http/`；公共字段见[配置协议](config.yaml)。
-
-## 监听与认证
-
-- `port` 省略或为 0 时不启用，1–65535 时启用；整个配置须启用 HTTP、SOCKS5 或 TUN。
-- `allow-lan` 默认为 false，绑定 `127.0.0.1`；开启时绑定 `0.0.0.0`。当全局 `ipv6: true` 时，同时绑定同端口的 `::1` 或 `::`，IPv6 socket 固定为 v6-only。
-- 操作系统明确报告地址族 / 协议不支持时可省略 IPv6 socket；地址占用、权限和其他绑定错误使整个启动失败。`ipv6: false` 不创建 IPv6 listener。
-- `authentication` 省略或为 `[]` 时，本机模式不要求认证；提供时必须恰好一项 `user:password`。按第一个冒号分隔，用户名与密码各为 1–255 UTF-8 字节，密码中的后续冒号保留，不 trim。显式 `null` 不是省略或空列表。
-- `allow-lan: true` 强制要求有效凭据；配置共享或非空凭据时必须有启用的 HTTP 或 SOCKS5 入站，二者共用这一组凭据。HTTP 共享通过 Basic 认证，不提供链路加密，只适合可信网络。
-- 配置了凭据就对每个请求独立认证，不继承同一连接前次请求的授权。缺失、错误、重复或格式不合法的 `Proxy-Authorization` 返回 `407` 并关闭连接，不建立上游。
-- Controller 保留独立的回环地址、Bearer secret 和路由，不随共享开关开放。
-
-配置片段（与节点、规则等共同使用）：
-
-```yaml
-port: 1080
-allow-lan: false
-ipv6: true
-authentication:
- - "proxy-user:proxy-password"
-```
-
-## 普通转发
-
-支持 HTTP/1.0 和 HTTP/1.1 的绝对形式 `http://host[:port]/path?query`。每个请求分别认证、确定目标、选路并建立上游；上游连接不跨请求复用。目标来自绝对 URI，转发成 origin-form 并重建 Host。
-
-客户端连接可依次发送多个请求，也可顺序预发送。固定读取缓冲区保存下一请求的预读字节，正文严格按照当前消息边界消费。只有请求允许 Keep-Alive、上传完成、响应有明确边界时才继续下一请求；不会把旧目标连接用作下一请求的上游。
-
-正文按流处理：
-
-- `Content-Length` 精确转发对应字节数，未带正文长度的普通请求视为空正文。
-- `Transfer-Encoding: chunked` 逐块解码边界并重编码，支持合法扩展语法和 trailer；扩展不向下一解析器透传，合法 trailer 保留。
-- HEAD、1xx、204、304 按无正文处理；1xx / 204 携带正文定界字段时失败关闭，HEAD / 304 可保留描述所选表示的长度。
-- 转发 HTTP/1.1 的 `100 Continue` 等临时响应。上传和读取响应并行，目标提前给出最终响应时终止上传、转发响应并关闭客户端连接，不把剩余正文作为新请求。
-- 普通响应无长度字段时由上游 EOF 定界，响应结束后关闭客户端连接。向 HTTP/1.0 客户端交付分块响应时去块并以关闭连接定界。
-
-歧义长度、重复 Content-Length、CL/TE 并存、非法分块、正文截断、非法控制字符和超限解析均失败关闭，不尝试恢复到下一请求。内部诊断字段、代理认证字段、Connection 指名字段及其他逐跳字段不会泄漏给目标；正文 trailer 不能携带认证、路由、消息定界或内部诊断字段。
-
-消息定界与连接管理依据 [RFC 9112 §6.3](https://www.rfc-editor.org/rfc/rfc9112.html#section-6.3)，逐跳字段依据 [RFC 9110 §7.6.1](https://www.rfc-editor.org/rfc/rfc9110.html#section-7.6.1)。VCore 对歧义输入采用严格拒绝策略。
-
-## CONNECT 与 Upgrade
-
-CONNECT 只在 Dispatcher 成功建立上游后返回 `200 Connection Established`。请求头后已经读到的数据保留，随后与新数据一起进入双向转发。建链失败返回对应错误，不提前确认隧道。
-
-HTTP/1.1 Upgrade 只接受无正文的请求。收到合法 `101`、Connection / Upgrade 字段一致且目标选择的协议在请求列表中时，才进入双向隧道。双方预读字节及 TCP 半关闭保留；非 `101` 响应按普通 HTTP 消息处理，非法切换返回 `502`。
-
-内部测速诊断只在**认证通过、监听地址为回环、客户端为回环、CONNECT 显式请求诊断**时返回。无认证的本机入口和共享入口均不返回内部错误详情，即使连接来自本机。
-
-## 生命周期与局部资源边界
-
-- 先取得 Controller 和全部业务地址族的监听 socket，再启动接收任务；任何一步失败释放已绑定 socket。业务连接按需创建，不设置全局连接数量准入上限。
-- 单个请求 / 响应头最多 32 KiB、100 个字段，读头总期限 10 秒；出站连接期限 10 秒。
-- 每个方向的预读 / 正文复制缓冲区为 8 KiB，正文长度不决定分配大小。chunk-size 行最多 1 KiB，trailer 合计最多 8 KiB / 100 个字段；每个最终响应前最多 16 个临时响应。
-- 正文每次读取 / 写入的空闲期限为 30 秒。上传期间并行等候响应，响应开始后使用独立读头总期限；上传结束后等待响应也有 10 秒期限。
-- Stop 覆盖读头、认证响应、建链、正文、CONNECT 和 Upgrade，取消后等待全部连接任务退出；端口在 Stop 返回后可重新绑定。
-
-自动化与 mihomo 双向进程互通的入口见[验收矩阵](acceptance.md)与[脚本说明](../scripts/README.md)。回环双栈测试不等于真实局域网或物理 IPv6 验收。
diff --git a/docs/inbounds.md b/docs/inbounds.md
new file mode 100644
index 0000000..8c31285
--- /dev/null
+++ b/docs/inbounds.md
@@ -0,0 +1,87 @@
+# HTTP 与 SOCKS5 入站
+
+两个客户端入口和 TUN 共用 Dispatcher、规则、DNS、静态 select 组及出站图。
+字段全集见[配置协议](config.yaml)，Controller 另见[接口](controller-api.md)。
+
+## 监听与认证
+
+- `port` 控制 HTTP；`socks-port` 控制同端口 SOCKS5 TCP/UDP。省略或 0 关闭，
+ 启用时为 1–65535；HTTP、SOCKS5、TUN 至少启用一个。
+- `allow-lan: false` 绑定 IPv4 回环，true 绑定通配地址。`ipv6: true` 增加独立
+ IPv6-only 回环/通配 socket。仅系统明确不支持地址族时可省略 IPv6，其余绑定错误
+ 整体回滚。取得 Controller 和全部业务 socket 后才启动接收任务。
+- `authentication` 省略或空列表时仅本机免认证；非空必须恰好一项 `user:password`，
+ 按第一个冒号拆分，两项各 1–255 UTF-8 字节，不 trim。null 不视为省略。
+ 共享强制认证；共享或非空凭据须有启用的 HTTP/SOCKS5 入口消费。
+- Basic / SOCKS 用户密码没有链路加密，只适合可信网络。Controller 仍独立回环监听，
+ 使用自己的 Bearer 认证，不随共享开关开放。
+- 不设置全局业务连接/关联准入数。Stop 取消并等待全部连接、relay 和接收任务，
+ 返回后端口可重新绑定。纯 SOCKS5 的独立 feature 不要求启用业务 HTTP。
+
+## HTTP
+
+每个请求独立认证，缺失、错误、重复或非法 Proxy-Authorization 返回 407 并关闭，
+不建立上游；前一个请求的授权不沿用到下一请求。
+
+### 普通转发
+
+HTTP/1.0 和 HTTP/1.1 使用绝对 `http://host[:port]/path?query` URI。每个请求重新
+确定目标、选路和建链，转发为 origin-form 并重建 Host，上游不跨请求复用。
+客户端可以 Keep-Alive 或顺序预发送；固定缓冲保存预读，只有上传完成且响应有明确
+边界才处理下一请求。不会把旧目标连接用于下一请求。
+
+- Content-Length 精确转发；没有正文长度的普通请求视为空正文。
+- chunked 按块解码并重编码；合法扩展不透传，合法 trailer 保留。
+- HEAD/1xx/204/304 无正文；1xx/204 携带正文定界字段失败关闭，HEAD/304 可保留表示长度。
+- 转发 100 Continue 等临时响应；上传和响应读取并行。提前最终响应会终止上传、
+ 转发响应并关闭客户端，不把余下正文误作新请求。
+- 无长度响应由 EOF 定界并关闭；HTTP/1.0 客户端接收 chunked 响应时去块后关闭。
+- 重复 Content-Length、CL/TE 并存、歧义长度、非法控制字符/分块、截断或超限均失败关闭。
+ 认证、内部诊断、Connection 指名及逐跳字段不泄漏给目标；trailer 不能携带认证、
+ 路由、定界或内部字段。
+
+定界遵循 RFC 9112 §6.3，逐跳字段遵循 RFC 9110 §7.6.1；歧义输入严格拒绝。
+
+### 隧道
+
+CONNECT 在上游成功后才返回 200，保留头后的预读数据。Upgrade 只接受无正文请求；
+合法 101、Connection/Upgrade 一致且选中请求协议时才切隧道，保留双方预读和 TCP
+半关闭。非 101 按普通响应处理，非法切换返回 502。
+
+内部测速诊断只在认证通过、监听和客户端均为回环且 CONNECT 显式请求时返回。
+无认证本机入口和共享入口不返回内部详情。
+
+### 局部上限
+
+头 32 KiB/100 字段、读头/建链 10 秒；每方向预读/复制 8 KiB。chunk 行 1 KiB，
+trailer 8 KiB/100 字段，每个最终响应前最多 16 个临时响应。正文逐次读写空闲期限
+30 秒；响应开始后独立计算读头总期限，上传结束后等待响应最多 10 秒。正文长度不
+决定分配大小，Stop 覆盖认证、建链、正文及隧道。
+
+## SOCKS5
+
+仅支持 RFC 1928/1929 的 SOCKS5 CONNECT、UDP ASSOCIATE 和用户名密码协商。
+不降级绕过已配置认证。精确读取握手并保留 CONNECT 后业务字节；上游成功才回复成功。
+目标保留 IPv4、IPv6 或域名交给 Dispatcher，入站不提前解析。TCP 每方向复制 4 KiB，
+保留半关闭。
+
+### UDP 授权
+
+- 一个有效 TCP 控制连接拥有一个关联。未授权 UDP 不创建状态或上游。
+- 请求源 IP 必须为未指定地址或 TCP peer IP；回复使用 TCP 连接实际本地地址和配置端口，
+ 不返回通配 relay 地址。
+- 授权键包含 TCP peer IP、从 TCP peer 取得的 IPv6 scope 和 UDP 源端口。
+ 端口 0 在首个合法且成功入队的数据报学习；同 IP/scope 最多一个待学习关联。
+ 明确端口可并存但不能重复授权，不同 scope 的链路本地地址互不串包。
+- 一关联可访问多目标，分别选路；回包保留出站提供的实际远端地址。
+- 非零保留位、分片、非法地址、零目标端口和超长包丢弃，不学习端口或续期。
+- TCP EOF/错误/Stop/过期撤销授权；旧任务不能删除新代次关联或发送旧回包。
+ 这比 Mihomo 任意 UDP 接收创建状态的策略严格。
+
+协商 10 秒；UDP 建链/单次发送/回包和 TCP 建链 15 秒。每关联队列 16 包，满时丢当前包；
+全局接收不等待慢建链。空闲 30 秒、每 10 秒检查，仅成功入队/发送的合法流量续期。
+wire 最大 65,507 字节，额外 sentinel 识别截断，自有 UDP socket 请求 65,508 字节
+发送缓冲；回包负载保守扣最大 262 字节头为 65,245 字节，嵌套出站继续扣预算。
+TUN 使用独立 MTU；SOCKS5 数据不计入 Controller 的 TUN 流量。
+
+[验收边界](acceptance.md)区分容器双栈与真实 LAN/物理 IPv6，不能相互替代。
diff --git a/docs/invoke-api.md b/docs/invoke-api.md
index 4afacce..a4e5295 100644
--- a/docs/invoke-api.md
+++ b/docs/invoke-api.md
@@ -1,6 +1,6 @@
# VCore Invoke API
-业务接口版本为 5，配置结构修订版为 14。配置只通过内联的 `configYaml` 或 `configYamls` 传入；每份已加载的 VCore 运行时最多拥有一个公共实例。代理组实时选择沿用 Controller，不增加 Invoke method 或版本协商。
+业务接口版本为 5，配置结构修订版为 27。配置只通过内联的 `configYaml` 或 `configYamls` 传入；每份已加载的 VCore 运行时最多拥有一个公共实例。代理组实时选择沿用 Controller，不增加 Invoke method 或版本协商。静态 ECH 只使用节点内联配置，不新增 bootstrap DNS 入参。
## C ABI
@@ -108,8 +108,8 @@ stopped -> preparing -> prepared -> starting -> running
```json
{
"apiVersion": 5,
- "buildIdentity": "VCore;engine=rust;coreVersion=0.1.0;invokeApiVersion=5;configVersion=14",
- "configVersion": 14,
+ "buildIdentity": "VCore;engine=rust;coreVersion=0.1.0;invokeApiVersion=5;configVersion=27",
+ "configVersion": 27,
"engine": "rust",
"version": "0.1.0"
}
@@ -316,7 +316,7 @@ ProtectFd(fd) -> bool
配置 `external-controller` 后，运行时可提供回环 `GET /traffic`、`GET /group`、`GET /group/{name}`、`GET /proxies/{name}` 和 `PUT /proxies/{name}`。代理组 Controller 可以在非 TUN 的 HTTP 或 SOCKS5 配置中运行；此时 `/traffic` 不存在。只要 Controller 管理代理组，`secret` 就必填并保护全部路由。
-组成员列表是配置期固定的，选择只存于当前 Running Session。成功切换只影响之后新建的物理 TCP、UDP 和 DNS transport，不迁移既有连接、UDP association、DNS 状态或 TCP pool，也不触发 failover。Controller 查询不携带 `instanceId`，不进入 Invoke 命令锁；完整语义见 [Controller API](controller-api.md)。
+组成员列表是配置期固定的，选择只存于当前 Running Session。成功切换只影响之后新建的物理 TCP、UDP 和 DNS transport，不迁移既有连接、UDP association、DNS 状态或 TCP pool，也不触发 failover。已认证 Hysteria2 会话的后续逻辑流和跳端口 socket 保留初始上游选择；新的认证会话才读取新选择。Controller 查询不携带 `instanceId`，不进入 Invoke 命令锁；完整语义见 [Controller API](controller-api.md)。
## Windows 安装包桥接
diff --git a/docs/outbounds.md b/docs/outbounds.md
new file mode 100644
index 0000000..c8dd581
--- /dev/null
+++ b/docs/outbounds.md
@@ -0,0 +1,191 @@
+# 客户端出站
+
+字段、类型与示例由 [config.yaml](config.yaml) 维护；这里只定义行为。
+VLESS/Vision/Encryption/JLS/ECH 见 [VLESS](vless.md)，XHTTP/sing-mux 见[专用契约](xhttp.md)。
+
+## 公共规则
+
+- 物理 TCP/UDP 只能由共享 Dialer 创建，保留 Android protect、Windows 物理绑定和受控解析。
+ 传输包装器只消费 IO，不另建 socket 或系统 resolver。
+- `dialer-proxy` 可引用节点或静态 select 组；与业务路由共享选择，完整 DAG 在配置期验证。
+ 一次建链使用组快照和同一绝对期限；已有连接不随切组迁移，无自动 failover 或 DIRECT 回落。
+- gRPC/legacy H2 首次读取延迟响应头时先检查原建链期限，即使响应已就绪也不能绕过
+ 超时；响应头已确认后的业务读取不再受该期限限制。
+- HTTP、SOCKS5、TUN、DNS 选路及 node-only `measureDelay` 使用同一连接器。
+ UDP 默认为 false；收发预算分别逐层扣封装开销，超限不截断交付。
+- TLS 使用共享 WebPKI、叶证书 pin/非叶信任锚与 skip 策略。pin 不匹配不能被 skip 绕过，
+ TLS 握手签名始终验证。节点策略与恢复缓存不可变、互相隔离，标准 TLS 总票据预算为 4。
+ 字段及模板详见 [TLS 证书与指纹](tls-client-fingerprint.md)。
+- 未知字段、null、错型、非法枚举或不适用的传输选项在网络 IO 前拒绝。
+ 凭据、UUID、业务目标和完整请求不进入 Debug/错误；资源与 Stop 见[公共策略](runtime-resource-policy.md)。
+
+## SOCKS5
+
+仅 SOCKS5 CONNECT / UDP ASSOCIATE；用户名密码成对配置，不支持 SOCKS4。
+TCP 保留域名交由上游解析；UDP 由控制连接拥有，校验 relay 来源并保留实际回包目标。
+上游为 select 组时，控制连接和后续 UDP 数据报使用同次建链快照。
+SOCKS5 不提供 TLS、证书 pin 或 ClientHello 模板；它的预算独立于 TUN MTU。
+
+## AnyTLS
+
+支持 v2、兼容 v1 的会话、内置填充与 UoT v2。password 为 1–1024 UTF-8 字节；
+SNI 默认 server；ALPN 省略/空列表不发送，非空保持顺序，不强制选中某协议。
+不开放 TLS 版本、ECH、mTLS、REALITY、填充和会话参数；命名指纹沿用共享 TLS。
+
+连接先发送 SHA-256 密码摘要、认证填充和首个会话批次。Settings 固定声明 v=2 和
+填充方案 MD5，不附产品/版本标识；合法 ServerSettings v>=2 启用 v2，否则兼容 v1。
+首个流与认证批次一起发送。复用空闲会话时，v2 写 SYN 和目标后即返回流，再监视
+最长 3 秒 SYNACK；v1 不等待。非空 SYNACK、超时、协议/读写器错误销毁整个会话，
+已返回流在后续 IO 报错。仅 open 返回前发现空闲会话失效时可新建一次；不重放业务。
+
+未知流、控制 ID/方向错误、越界负载或非法设置是会话级错误；Alert/非空 SYNACK
+仅返回固定诊断，不向日志或调用方回显远端内容。
+一个物理会话同时仅一个活动流，完整结束后入空闲列表；优先复用序号最大者。
+检查/空闲超时均 30 秒，不预热；首次使用才启动清理 worker。ID/序号耗尽关闭会话。
+
+写命令队列 2 项，流接收容量按运行时预算推导且至少 1；活动会话不设全局数量上限。
+UoT v2 使用 `sp.v2.udp-over-tcp.arpa:0` 数据报模式，首包含请求，之后每包携带
+IP/域名目标，协议负载最多 65,535 字节并取调用方预算交集；响应队列 1 项。
+关闭/取消/丢弃 UoT 同时结束读取任务和底层流。
+
+填充为内置方案；新物理会话持有不可变快照，合法 UpdatePaddingScheme 仅影响后续
+会话，非法更新只产生有界警告。文本、条目、逻辑填充量和帧负载都有界。
+begin_shutdown 同步禁止新流、清空空闲并取消所有会话；shutdown 等待清理 worker、
+读写器和 UoT 任务。准备回滚、运行时 Stop 和测速返回前均完成此屏障，不跨运行时共享。
+
+## Trojan
+
+固定 TLS，network 为 tcp/标准 ws/grpc，默认 tcp。密码为非空原始 UTF-8，不 trim，
+认证为 SHA-224 小写十六进制。无认证 ACK：本地建链成功不代表密码通过，负例须检查
+原站零业务字节。
+
+SNI 默认 server；WS Host 只覆盖 HTTP authority，不作为 SNI 回退。ALPN 默认 TCP 空、
+WS http/1.1、gRPC h2，显式列表及实际协商均须满足传输，不能静默降级。
+
+WS path 默认 /，可带 query；头字段不得覆盖握手保留头或大小写重复。early-data
+0–2048 字节，启用时默认 Sec-WebSocket-Protocol，可自定义；空头名表示路径后缀，
+此时禁止 query。禁用时不能附 ED 头名。首请求头与剩余数据只按序发送一次。
+gRPC service-name 必填，普通名映射 /name/Tun，以 / 开头则为完整路径；不开放池参数。
+
+TCP 保留半关闭；gRPC duplex 发送 END_STREAM，不用 RST_STREAM 提前结束读侧。
+UDP 使用同一已认证流上的地址/长度/CRLF 帧，无额外 socket/读取泵/池。
+payload 最多 8192 字节，待解析最多 8455 字节，并与调用方收发预算分别取交集。
+非法/截断帧关闭，合法超接收预算整包丢弃；取消读取保留进度，部分发送取消使关联失效。
+运行时先取消并 join 入站所有者，再等待节点 gRPC 驱动。
+
+## VMess AEAD
+
+标准 UUID，alterId 仅省略/0，请求和响应头均 AEAD，无旧认证回退。cipher 为 auto、
+aes-128-gcm、chacha20-poly1305、none；zero 归一 none。auto 按实际 AES 硬件能力选择。
+none 只关闭 body 加密，仍验证响应身份；不能启用 global-padding/authenticated-length，
+两开关默认 false。
+
+network 默认 tcp，另支持 ws/grpc/http/h2；均可明文或标准 TLS。tls 默认 false，
+关闭时禁止 TLS 字段，即便空串、空列表或 false。认证名依次为 servername、WS Host
+去端口、server；HTTP 伪装 Host/H2 authority 不替代认证名。WS 需 http/1.1，gRPC/H2 需 h2。
+
+- WS ED/路径/头约束同 Trojan。
+- gRPC service-name 必填，普通名/完整路径规则同 Trojan，无额外池调度器。
+- http 是 TCP 首包伪装：method 默认 GET，path 列表省略/空为 /，按 URL.Path 转义；
+ 头为字符串列表，每次握手独立选择路径/头值，Host 默认物理 server authority。
+ 仅首包封装一次，之后恢复原流；禁止 Content-Length/Transfer-Encoding。
+- h2 需要非空 authority 列表，path 默认 /，每流选一个 authority，通过 HTTP/2 PUT body
+ 双向传输；明文 prior knowledge、TLS h2，无 gRPC 帧。
+
+关闭对齐 Mihomo：TCP/WS 可保留上传 EOF 后的读取；gRPC/HTTP/H2 关闭整条逻辑流，
+完整响应应在关闭前读取，不统一要求半关闭尾包。
+
+UDP packet-encoding 默认空串（raw），外层仍 TCP：
+
+| 编码 | 目标与预算 |
+| --- | --- |
+| raw | 首目标写入认证头；同关联换目标失败，等待首包不重置组快照/建链期限 |
+| xudp | 每帧携带目标，零 global ID 不发可选扩展；内部 mux 标记不解析 DNS |
+| packetaddr | 每包仅 IP+端口，业务域名用运行时受控 DNS；没有 resolver 时不回退系统 DNS |
+
+UDP body 最多 15,000 字节；packetaddr 另扣 IPv4 7 / IPv6 19 字节，未解析域名按 19
+预检；超限一字节即写前失败，不拆业务包。对端可能更小，V2Ray 部分返回路径总缓冲
+仅 2048 字节，不能当作 VCore 上限。body wire 解析最多 16 KiB，响应头/XUDP 元数据有界。
+TCP 写块最多 4 KiB 以适配 Mihomo 拷贝边界；UDP 不按此切块。16 位帧计数耗尽前关闭，
+不重复 nonce。半帧发送取消关闭，接收取消保留进度；认证/地址/标签错误使关联失效。
+gRPC/H2 driver 由节点跟踪并同步退出，无全局会话额度或历史表。
+
+## Hysteria2
+
+始终 QUIC/TLS 1.3，使用官方 rustls；不接受 tls/network/client-fingerprint/REALITY。
+port 为 1–65535，仅提供 ports 时可省略；显式非法 port 仍拒绝。password 默认空、
+保留原值，须为最长 8192 字节的合法 HTTP 头值。SNI 默认 server；ALPN 省略/空为 h3。
+支持共享证书 pin/skip 和成对内联 PEM mTLS；udp 只控制业务 UDP，不关闭 QUIC 载体。
+
+- up/down 独立非负整数或十进制整数字符串，裸值 Mbit/s；单位 [KMGT]?[bB]ps 使用
+ 十进制倍率，bit 向下取整为 byte/s。省略/归一零为自动；拒绝小数、符号、溢出。
+- udp-mtu 缺省/0 为 1197，其他值 64–65535，限制编码后单分片并取实际 DATAGRAM
+ 预算交集，不是 TUN MTU。
+- obfs 只允许 salamander，须配非空独立 obfs-password。
+- ports 是归一去重的非空端口/闭区间集合，优先于合法 port。hop-interval 仅随 ports：
+ 整数秒 N、字符串 N 或 N-M，默认 30，5 ≤ N ≤ M ≤ u32::MAX；过短严格拒绝。
+
+每节点一个当前认证 QUIC 会话，逻辑流/关联复用且互不取消。HTTP/3 POST hysteria/auth
+在业务前要求 233；TCP 类型 0x401，响应可延迟到首次读取，允许先写业务。
+认证/上游/请求共用绝对 10 秒预算。旧会话失败后新流可新建会话，已有业务不重放。
+写 EOF 关闭当前逻辑 TCP 双向通道，与 Mihomo 一致，不影响兄弟流。
+
+每流接收窗口 256 KiB、连接收发各 1 MiB、DATAGRAM 收发各 256 KiB；最多 8 条单向
+控制流，拒绝主动双向流。PMTUD 关闭，最大 QUIC payload 1400 并取上游预算交集；
+空闲 30 秒/保活 10 秒。认证头 16 KiB，TCP 响应消息 2048/padding 4096 字节。
+业务 UDP 原生 DATAGRAM，payload 最多 4096，最多 255 分片；未知关联不创建状态。
+重组按关联/包/地址隔离，最多 64 个待完成包/256 KiB、TTL 5 秒，关联交付队列 32 包。
+重复未完成分片忽略；完成后立即释放 16 位 Packet ID，允许后续重用，**不做业务去重**。
+
+down 写入 Hysteria-CC-RX。up=0 或服务端 auto 使用 BBR，否则取 up 与服务端正上限
+较小值（服务端 0 无限），使用固定带宽控制与实际 wire-byte pacer。Mihomo down=0
+可能返回 RxAuto，优先自动模式。丢包补偿五秒窗口、最小采样量、ACK 比例下限 0.8。
+Salamander 采用公开 salt + XOR/BLAKE2b-256，每包加 8 字节，先扣 QUIC 预算但计入
+pacer；这是混淆不是认证，错误密钥由 QUIC 拒绝，短包有界丢弃。
+
+端口集合须映射同一服务端 QUIC 状态；初始/后续随机选端口。跳跃创建新受控 socket，
+保持认证时组快照，独立期限不延长初始认证、不重认证。发送只走新路径；一秒内公平
+接收新旧路径，最多两条，之后回收旧路径。Stop 同步 join 路径/重组/HTTP3/QUIC，
+关闭交换最多一秒。
+
+官方 Hysteria 已验证版本的 4096 字节回包缓冲包含头，更大回包可能在分片前丢弃。
+原生测试记录实际版本和限制，VCore 完整 4096 字节另对 Mihomo 验证，不修改第三方。
+
+## Shadowsocks 2022
+
+原样复用官方 shadowsocks-rust，仅三算法：
+
+| cipher | 密钥 |
+| --- | --- |
+| 2022-blake3-aes-128-gcm | 16 字节 Base64 PSK，或有序 iPSK1:…:iPSKn:uPSK |
+| 2022-blake3-aes-256-gcm | 32 字节，同上 |
+| 2022-blake3-chacha20-poly1305 | 单一 32 字节 Base64 PSK |
+
+标准 Base64 可省末尾 padding；空段/非法编码/长度错误拒绝，凭据不 trim。
+官方库只包装已有 TCP 流，UDP codec 单包有界交接，不调用其 socket 工厂。
+
+- TCP 每次最多交付 16 KiB；读或关闭先于首次写时，完成并刷新官方空首写以支持
+ server-first/半关闭。Pending 继续同次握手，已有首写不重复目标头。
+- 背压适配最多暂存一个 16 KiB 原文块并立即报告接受；后续保持同缓冲完成写入，
+ 避免官方重试长度误计。flush/关闭排空，读取也推进待写但不被写背压阻塞。
+- UDP 取消前预留 packet ID，底层实际发送后才成功；Pending 不重编码，无后台发送队列。
+ 接收验证来源、认证、关联与完整负载，外层 wire 最大 65,507。
+- 每关联随机 client session ID、递增 packet ID，最多两个 server session 的 8128 包
+ 重放窗口；旧 session 一分钟仍有有效包时不替换，ID 将溢出时换 client ID 并清空窗口。
+ close 清空并关闭底层，不新增后台任务。
+
+依赖仅 crates.io 版本，不使用 Git/path/源码补丁。AWS-LC 仅允许沿 shadowsocks →
+shadowsocks-crypto 链使用，TLS/REALITY 不消费它，详见[TLS 依赖](tls-dependencies.md)。
+启用 SS 时通过 log 的 max_level_off/release_max_level_off 关闭整个依赖图该 facade，
+防止上游日志泄密；VCore tracing 不受影响。上游 Debug 不暴露。
+重放窗口派生代码的来源/完整许可保留在源码头，发布仍审计实际链接图。
+
+**已知风险：**原样上游空 TCP 首写/空 UDP padding 路径扩展长度而未显式初始化，
+存在把残留缓冲传给可解密对端的风险；普通 echo 或自有背压修复不代表此风险已解决。
+官方空 TCP 首写还可能随机生成零 padding，被其严格服务端拒绝；VCore 不修改或重试
+该上游行为。内存回归分别验证适配器刷新与确定性的零 padding 拒绝，不将 codec
+级回复算作 server-first 互通通过。
+首次固定头不够单次读取时，上游按探测防护拒绝，不改成 read_exact。
+Mihomo 仅提供单 PSK；原样 ssserver 验证 AES 单层 EIH 多用户 TCP/UDP 终结及错误身份。
+MTU1500 大包夹具显式启用官方双向 IP 分片。自有 1/2 层身份中继不是原生任意多层证明。
+所有结果与平台/发布签收分开，见[验收边界](acceptance.md)。
diff --git a/docs/reality-wire-protocol.md b/docs/reality-wire-protocol.md
index 3775961..21b729a 100644
--- a/docs/reality-wire-protocol.md
+++ b/docs/reality-wire-protocol.md
@@ -1,34 +1,47 @@
# REALITY V1 客户端协议
-本文定义 VCore 自有 rustls fork 当前实现的 classic REALITY V1 客户端线上行为。它不是通用 REALITY 规范，也不承诺浏览器 ClientHello 模拟。
+本文定义 VCore 的 REALITY V1 客户端线上行为。它不是通用 REALITY 规范。经典模式为默认，配置修订版 22 可显式要求混合密钥交换。可选的四套 ClientHello 模板及混合兼容边界见 [TLS 指纹](tls-client-fingerprint.md)。
## 版本边界
-当前实现基于 rustls 0.23 系列。线上行为由本文和 fork 内的确定性测试向量共同约束。升级 rustls、加密提供方或任一握手字节时，必须重新验证普通 TLS、REALITY、并发、取消和目标平台构建。
+当前 REALITY 实现基于自有 boring 5.2.0 fork 的原生 BoringSSL 扩展。线上行为由本文和 fork 内的确定性测试向量共同约束。升级 TLS 后端、加密提供方或握手字节时，必须重新验证普通 TLS、REALITY、并发、取消和目标平台构建。
V1 只支持：
- 客户端模式；
- TLS 1.3；
-- X25519；
+- 经典 X25519，或显式要求 X25519MLKEM768 的 TLS 密钥交换；
- classic Ed25519 临时证书认证；
- 0–8 字节 short ID，在线上右侧补零到 8 字节；
-- `ring` 加密提供方。
+- BoringSSL 原生握手和加密实现。
-不支持 REALITY 服务端、TLS 1.2、QUIC 传输、ECH、HelloRetryRequest、会话恢复、0-RTT、混合后量子密钥交换、浏览器指纹或 `fp`。收到 HRR 或 REALITY 认证失败时立即终止，不降级为普通 WebPKI。
+不支持 REALITY 服务端、TLS 1.2 协商、QUIC 传输、实际 ECH、HelloRetryRequest、会话恢复、0-RTT 或 `fp`。ECH GREASE 与实际 ECH 不同。收到 HRR 或 REALITY 认证失败时立即终止，不降级为普通 WebPKI。
## ClientHello 认证
-每个 `ClientConnection` 独占一份 X25519 临时私钥，同时用于：
+每次 REALITY 认证绑定本次原生 SSL 握手中的一份真实 X25519 临时私钥，同时用于：
-1. TLS 1.3 ClientHello 的 X25519 key share；
+1. TLS 1.3 ClientHello 的实际 X25519 share，或混合 share 中的 X25519 分量；
2. 与配置中的服务端静态 X25519 公钥执行 ECDH。
VCore 不能读取该私钥，也不能为两个用途生成不同密钥。
+原生封装按实际 GroupID 找到唯一 X25519 share，不依赖 share 下标。Firefox 可保留
+额外 P-256 share，但认证始终绑定同一 X25519 临时私钥。Chrome133 的普通 TLS
+ML-KEM group/share 在 classic REALITY 中裁剪。显式混合模式保留模板中的真实混合 share；
+无命名指纹时只提供混合 share。若同时存在独立 X25519，优先用它派生认证，否则使用
+实际混合 share 内的 X25519 分量，与 Mihomo 的认证取值一致。
+重复/缺失认证 share、低阶点均失败。显式混合模式还在 ServerHello 处理时要求
+实际选择 group 4588，经典组或 HRR 立即失败，不重新发起经典握手。REALITY 身份
+认证仍是经典 X25519/Ed25519，不能将混合 TLS 密钥交换称为后量子身份认证。
+
ClientHello 的 legacy session ID 固定为 32 字节。生成密文前先把该字段清零，再编码完整 TLS Handshake `ClientHello`，将其作为 AES-GCM 的 AAD。
-`signature_algorithms` 必须公布当前加密提供方完整支持的 ECDSA、RSA 和 Ed25519 算法。REALITY 使用 Ed25519 临时证书不意味着 ClientHello 只能声明 Ed25519；完整列表用于让采用 ECDSA/RSA 证书的伪装站点正常进入握手，不会放宽后续 REALITY 身份校验。
+`signature_algorithms` 保留所选模板的列表；REALITY 不强行加入 Ed25519。原生实现仅在临时证书先通过 REALITY HMAC 认证后，允许它的 Ed25519 CertificateVerify，并仍验证签名。该局部例外不放宽普通 TLS 的签名算法检查。
+
+命名指纹保留 TLS1.2 的版本/cipher/扩展声明（Safari 的 TLS1.0/1.1 仍裁剪），
+而非先用 TLS1.3-only 的通用编码过滤模板。原生 REALITY 在 ServerHello 阶段独立拒绝
+TLS1.2，且仍禁止恢复、0-RTT 和普通证书兜底；声明并不代表允许降级协商。
session ID 明文前 16 字节为：
@@ -72,13 +85,13 @@ session_id = AES-256-GCM-Seal(auth_key, nonce,
## 状态与资源
-共享 `Arc` 只保存不可变的服务端公钥、short ID 和客户端版本。临时私钥、ECDH 结果、`auth_key` 和已认证公钥只存在于单个连接中，不使用全局表、跨连接锁或共享认证槽位。
+共享连接器只保存不可变的服务端公钥、short ID、客户端版本和模板策略。临时私钥、ECDH 结果、`auth_key` 和已认证公钥只存在于单个连接中，不使用全局表、跨连接锁或共享认证槽位。
连接取消、失败或释放时清零临时私钥、共享密钥和 `auth_key`。证书解析深度和输入大小固定，不依据对端长度创建无界容器。fork 不创建线程、异步任务、连接池或队列。
## 固定向量
-rustls fork 的测试固定：
+boring fork 的测试固定：
- RFC 7748 X25519 私钥、公钥和共享密钥；
- 清零 session ID 的 ClientHello AAD、HKDF 结果和 32 字节 REALITY session ID；
@@ -86,4 +99,4 @@ rustls fork 的测试固定：
- 截断或非规范 DER、错误 HMAC、错误签名、缺失状态、低阶公钥和 HRR 负例；
- 多配置并发和连接状态隔离。
-VCore 的互操作测试还覆盖 XHTTP 模式、取消重连、错误 key/short ID 和普通 TLS 回归。实际执行范围见 [验收矩阵](acceptance.md)，依赖发布要求见 [rustls REALITY 依赖](rustls-reality-release.md)。
+VCore 的互操作测试还覆盖 XHTTP 模式、取消重连、错误 key/short ID 和普通 TLS 回归。实际执行范围见 [验收矩阵](acceptance.md)，依赖发布要求见 [TLS 依赖](tls-dependencies.md)。
diff --git a/docs/runtime-resource-policy.md b/docs/runtime-resource-policy.md
index bb16ad2..1c39586 100644
--- a/docs/runtime-resource-policy.md
+++ b/docs/runtime-resource-policy.md
@@ -37,19 +37,26 @@ Windows L3 接口及其 Session Host netstack 使用 1400 MTU，因此按 IPv6 U
## TCP 与握手
- TCP 流按需创建任务，每方向缓冲区固定为 32 KiB。
-- TLS/XHTTP 内部缓冲区固定为 64 KiB。
+- rustls/XHTTP 的配置缓冲区为 64 KiB；boring 每次应用写入最多 min(节点缓冲预算, 16 KiB)，原生 TLS 记录有界，命名模板证书消息/解压输出另限 128 KiB。
- 标准 TLS 恢复会话总预算为 4，按节点（含独立下载端点）分配；每个缓存绑定不可变的 SNI、ALPN 和证书策略，绝不跨节点复用。TLS 1.3 票据有界、一次性消费，TLS 1.2 会话占用同一额度；额度为 0 则禁用恢复。REALITY 不参与该缓存。
+- 共享 TLS 客户端的显式验证名、协议版本、客户端证书身份和 ClientHello profile 也属于不可变策略，单独构造缓存，不跨身份共享。boring 只保存当前节点/SSL 上下文产生的票据，应用层 ALPN 接受前不发布，失败或取消丢弃临时票据。标准 TLS 和 REALITY CloseWrite 只发送 close_notify，刷新最多5秒，保持读方向和底层传输；Drop 释放整个流。XHTTP 仍以逻辑连接整体关闭为准。
- 半开连接、出站握手和活动会话只记录当前值和峰值，不触发资源错误。
- 超时、取消、EOF 和协议错误负责回收；停止必须等待全部已跟踪任务结束。
- 引导解析器最多使用四个工作线程；全部忙时在调用方既有期限内等待，不返回人为容量错误。
-## HTTP 代理入站
+## 共享流传输基础
-HTTP 代理入站不是 TUN 转发缓冲区的使用者：请求 / 响应各使用 8 KiB 预读与复制缓冲区，头部 32 KiB / 100 字段、chunk 行 1 KiB、trailer 8 KiB / 100 字段。正文不整体缓存，不设全局业务连接准入数；先绑定后启动，Stop 取消并等待所有入站连接任务。读头、正文空闲和临时响应数量边界见 [HTTP 代理入站](http-proxy.md)。
+`stream-transport` 仅包装传入 IO，不创建 socket 或 DNS。WS/HTTP响应首部最多16 KiB、100字段；WS用户请求头最多100字段，额外固定升级头和early-data仍计入16 KiB总预算。WS early-data最多2,048原始字节，头名称/路径后缀由类型化选项区分。WS消息和单帧最多64 KiB，写入切块16 KiB；HTTP首包正文直接写入，不整体复制或持续按HTTP正文定界。
-## SOCKS5 代理入站
+共享的无池gRPC/legacy H2适配器每个实例仅拥有一条底层连接与一个逻辑流，不是全局并发许可；VLESS另有下文描述的节点级gRPC池。流窗口64 KiB、连接窗口128 KiB、最大HTTP/2帧和发送缓冲各16 KiB、解码负载64 KiB。读侧按实际消费量释放窗口；每poll最多处理32个片段/控制消息。原有gRPC和legacy H2的shutdown关闭整个逻辑连接；Trojan使用独立duplex模式，仅发送END_STREAM并保留读取。关闭前已接受的数据须到达所提供IO的flush边界，不能仅排入h2队列后立即reset/abort；每个逻辑写端最多一个待确认数据块，Stop可取消等待。两种模式的owner.stop都等待驱动任务退出；Drop只做取消兜底，不作为同步停止通过证据。WS/HTTP适配器按底层CloseWrite语义工作，协议包装层可以根据Mihomo契约结束整个逻辑流。所有握手使用调用方同一个绝对deadline。
-TCP 每方向复制缓冲区 4 KiB，握手 10 秒。UDP 控制连接拥有授权、单关联 16 包队列及 relay；全局接收不等待建链或发送。空闲 30 秒、每 10 秒清理，满队列与非法包不刷新时间。UDP wire 上限 65,507 字节，回包负载保守预留最大头部为 65,245 字节，出站继续逐层核算预算；不复用 TUN MTU。Stop 等待全部任务退出，无全局关联数准入。完整语义见 [SOCKS5 入站](socks5-proxy.md)。
+XUDP现在只拥有已认证流上的帧编码；VLESS响应头由VLESS包装层处理。元数据仍最多512字节，单payload仍受调用方预算和u16 wire上限约束，不新增全局会话额度。
+
+## 协议局部预算
+
+协议专用上限与关闭语义只维护在[入站](inbounds.md)、[出站](outbounds.md)、
+[VLESS](vless.md)和[XHTTP/sing-mux](xhttp.md)。`tests/protocols/limits.json`
+绑定实际常量与越界用例，不是第二套运行时配置或可配置业务准入数。
## UDP
@@ -65,6 +72,16 @@ TCP 每方向复制缓冲区 4 KiB，握手 10 秒。UDP 控制连接拥有授
嵌套代理协议可以增加有界帧头，但最终解封装负载仍不得超过调用方按有效 MTU 给出的上限；其他 TUN 平台为 1,452 字节，Windows 为 1,352 字节。
+### 定向数据报预算与受控 QUIC
+
+`DatagramBudget` 分别表达当前层的发送和接收 payload 上限。嵌套协议先为下层申请有界 envelope 空间，再按实际协议/地址族开销扣除下层能力，与调用方预算取交集；不能把接收上限直接当作发送能力。DIRECT、SOCKS5、SS 2022、AnyTLS UoT 和 VLESS XUDP 保留原来对端/地址校验。超出发送预算在写入前失败，超出接收预算丢当前包并有界让出执行权，close 后不能恢复收发。
+
+`quic-transport` 只把已有 `DatagramTransport` 适配成 Quinn 的受控 UDP 接口，没有内部 bind、DNS 或 DIRECT 回落。每个连接双向各最多32个排队数据报，另允许一个正在发送的包；TX满返回WouldBlock，RX满暂停读取。接收等待不会持有发送队列锁；Pending发送不会重复提交。单逻辑peer/物理peer映射和来源校验独立保留，不接受未请求的目标、GSO或源地址覆盖。物理 socket 仍只能来自 Dialer。
+
+QUIC双向可用payload至少1,200字节；endpoint必须显式把QUIC MTU限制在有效预算内。IPv4/IPv6路径MTU分别先扣除28/48字节IP+UDP头，边界和单字节不足均有定向测试。
+
+QUIC owner.stop先取消并等待驱动，再关闭并释放上游；上游close最多1秒。Driver Drop仅为取消/abort兜底，不能作为同步Stop验收。队列容量是单连接局部界限，不是全局QUIC连接准入数。
+
## DNS
- 不设置固定的活动请求或活动传输总许可数。
@@ -78,11 +95,13 @@ TCP 每方向复制缓冲区 4 KiB，握手 10 秒。UDP 控制连接拥有授
完整语义见 [TUN ICMP 与 DNS](tun-icmp-dns.md)。
+IP-only协议接点持有`ResolutionContext`，runtime DNS通过Weak绑定，不形成DNS→dispatcher→connector强引用环。解析继承同次建链绝对期限和runtime取消；同名递归/超过32层解析依赖立即失败，32是单调用依赖深度而非并发请求额度。独立测速的受控bootstrap上下文不创建Running Session或RuntimeDns。
+
## 代理组与 Controller
- 静态 `select` 组只拥有不可变的有序成员和每组一个可原子替换的当前索引，不拥有协议连接、后台任务、队列、缓存或独立 worker。
- 组数、每组成员数、重复成员数和嵌套深度没有独立固定上限，统一受 256 KiB YAML 上限约束；配置期使用 O(V+E) 的迭代 DAG 校验，运行时也以迭代方式解析当前叶节点。
-- 节点上游和全部组成员在同一 DAG 中校验；组连接器只持有声明依赖，按逆依赖顺序释放。建链快照只按需记录本次遇到的组，随建链结束释放，不成为全局缓存或长生命周期状态。
+- 节点上游和全部组成员在同一 DAG 中校验；组连接器只持有声明依赖，按逆依赖顺序释放。建链快照只按需记录本次遇到的组，不成为全局缓存。Hysteria2 的已认证连接为后续端口跳跃保留该快照，直到此物理会话退出；它不再读取实时选择，也不延长原建链期限。
- 同组成功选择是线性化的，不同组独立；选择失败不改变状态，也不创建重试或自动 failover 任务。
- 切换不扫描或迁移现有 TCP、UDP、DNS transport，不刷新 DNS cache/singleflight 或 TCP pool；资源仍由原所有者按既有 timeout、EOF、取消和 stop 语义回收。
- Controller 同时最多跟踪 8 个连接任务。请求 header 和 PUT body 各有 5 秒读取期限，PUT body 最大 1 KiB；超时、超限和解析失败只终止当前请求。
@@ -115,6 +134,10 @@ Apple 目标通过 `TASK_VM_INFO` 尽力记录当前 physical footprint、进程
日志必须有界且脱敏，不记录目标、DNS question、UUID、凭据、密钥、负载或完整配置。
+仅`cfg(test)`/`interop-test`启用的`ResourceProbe`按测试作用域记录RAII当前值/峰值；子任务显式继承作用域，不使用进程全局reset或更换生产allocator。当前接入物理TCP/UDP、共享流/QUIC驱动与session、数据报association、DNS池/等待者及既有运行时活动guard。Hysteria2 的待完成分片通过 `Reassembly` 登记，交付后释放 Packet ID 和重组资源；零计数必须与实际执行过的重组路径一起解释。
+
+生产`ObservedIo`中的观测guard为空类型，不分配共享计数器。同步Stop、5秒静默窗口和真实对端由断言及结构化事件证明，不根据日志中的PASS文字判断。`tests/protocols/limits.json`登记公共限额及继承的`ResourceLimits`，`limit_foundations`直接与Rust常量核对；它不是第二套运行时配置。
+
## 变更要求
新增全局 admission、可配置容量或长期缓存前，必须：
diff --git a/docs/rustls-reality-release.md b/docs/rustls-reality-release.md
deleted file mode 100644
index 23e3307..0000000
--- a/docs/rustls-reality-release.md
+++ /dev/null
@@ -1,71 +0,0 @@
-# rustls REALITY 依赖与发布要求
-
-VCore 的 REALITY 客户端依赖自有 rustls 0.23 fork。仓库通过 GitHub 分支 `vcore/reality-0.23` 引用该 fork，并由 `Cargo.lock` 固定实际解析的提交。
-
-## 实现边界
-
-fork 只增加连接级 REALITY 能力：
-
-- 配置构建器接收不可变的服务端公钥、short ID 和客户端版本；
-- ClientHello 使用同一 X25519 临时密钥完成 key share、ECDH 和 session ID 封装；
-- 证书验证器消费当前连接的认证状态，验证临时证书和 TLS 1.3 `CertificateVerify`；
-- 所有失败路径清零秘密并终止连接。
-
-fork 不创建线程、异步任务、连接池、全局映射或跨连接锁。VCore 只负责配置解析并选择普通 TLS 或 REALITY；握手字节和认证状态属于 rustls。
-
-普通 TLS 与 REALITY 必须使用不同的不可变 `ClientConfig`，不能在同一对象上热切换身份。线上协议见 [REALITY V1 客户端协议](reality-wire-protocol.md)。
-
-## GitHub 分支依赖
-
-```toml
-[patch.crates-io]
-rustls = { git = "https://github.com/OneVCore/rustls", branch = "vcore/reality-0.23" }
-```
-
-要求：
-
-1. 只使用上述 GitHub 分支，不使用本机路径或第二个 rustls source；
-2. `Cargo.toml` 和 `Cargo.lock` 在同一提交中更新，lockfile 必须包含实际解析的完整 Git revision；
-3. 没有相邻 rustls 目录时，`cargo fetch --locked` 和后续构建仍能成功；
-4. 只启用预期的 `ring` 提供方和 REALITY feature；
-5. 发布记录保存 VCore revision、lockfile 中的 rustls revision、lockfile hash 和产物 SHA-256。
-
-分支前移不会自动改变 locked 构建。升级必须显式更新 `Cargo.lock`、审查解析 revision，并在同一变更中重新执行验证门禁。
-
-## 验证门禁
-
-在全新目录中执行：
-
-```bash
-cargo fetch --locked
-cargo fmt --all -- --check
-cargo test --locked --all-features --all-targets
-cargo clippy --locked --all-features --all-targets -- -D warnings
-uv run --project scripts --locked vcore-scripts check c-header
-uv run --project scripts --locked vcore-scripts check tls-dependencies
-uv run --project scripts --locked vcore-scripts build apple
-uv run --project scripts --locked vcore-scripts build android
-uv run --project scripts --locked vcore-scripts build windows
-```
-
-同时验证：
-
-- 普通 TLS 与 REALITY 的真实进程数据面；
-- 错误 public key、short ID、伪装站证书和 HRR；
-- 共享连接器并发、取消重连和运行时停止；
-- AnyTLS 继续使用标准 TLS，不继承 REALITY 身份；
-- Apple、Android 和 Windows 产物使用同一锁定依赖。
-
-具体执行结果只记录在 [验收矩阵](acceptance.md)。
-
-## 升级与回退
-
-升级 rustls 基线或加密依赖时，单独完成以下变更：
-
-1. 同步上游并先解决普通 TLS 回归；
-2. 重新运行全部确定性线上向量；
-3. 审查 ClientHello、key share、证书验证器和 provider API 的变化；
-4. 重新执行平台构建和产品数据面；
-5. 推送分支提交并更新、审查 lockfile 中的解析 revision。
-
-回退通过新的 VCore 提交恢复上一个已验证 lockfile revision。VCore 不保留双 REALITY 实现或运行时降级开关。
diff --git a/docs/shadowsocks.md b/docs/shadowsocks.md
deleted file mode 100644
index 238bec5..0000000
--- a/docs/shadowsocks.md
+++ /dev/null
@@ -1,41 +0,0 @@
-# Shadowsocks 2022 出站
-
-`outbound-shadowsocks` feature 使用原样官方 `shadowsocks-rust` 协议库，仅开放下列三种算法；配置纳入修订版 14。字段与示例见 [config.yaml](config.yaml)。本机协议与适配器验收见 [acceptance.md](acceptance.md)，不等同于完整组合或目标设备发布验收。
-
-## 配置与密钥
-
-`type: ss` 接受公共节点字段 `name`、`server`、`port`、`udp`、`dialer-proxy`，及必填 `cipher`、`password`。`udp` 默认 false；上游可引用具体节点或静态 select 组。
-
-| cipher | 解码后密钥长度 | password |
-| --- | --- | --- |
-| `2022-blake3-aes-128-gcm` | 16 字节 | Base64 PSK 或 `iPSK1:…:iPSKn:uPSK` |
-| `2022-blake3-aes-256-gcm` | 32 字节 | Base64 PSK 或 `iPSK1:…:iPSKn:uPSK` |
-| `2022-blake3-chacha20-poly1305` | 32 字节 | 单一 Base64 PSK |
-
-算法名称精确匹配。标准 Base64 可带或不带末尾 padding；空段、非法编码与密钥长度错误在配置验证时失败。AES 身份链保持声明顺序，末段是用户密钥；不 trim 凭据，不在错误或 Debug 中展示密钥。
-
-## I/O 与关联状态
-
-- 官方库仅包装 VCore 已有 TCP 流，UDP codec 使用单包有界交接；不调用官方库的物理 socket 创建接口。物理首跳继续经过共享 dialer、预解析端点、Android protect 和 Windows 绑定。
-- TCP 按 16 KiB 部分写入交付 codec，确保首次目标头与负载落在协议帧上限内；读取或关闭写端先于首次写入时调用官方空首写，允许服务器先发或在客户端半关闭后响应。空首写遇到 Pending 时继续完成同一次握手，再关闭底层写端；已有负载首写不重复目标头。错误只保留错误种类与固定消息。
-- UDP 在可取消发送前预留 packet ID，真实底层发送结束才报告成功；Pending 不触发重复编码，无后台发送队列。接收只交付完整数据报，并检查来源、认证、响应 payload 上限和关联 ID。
-- 每个 UDP transport 保留随机 client session ID、递增 packet ID，以及最多两个 server session 的 8,128 包滑动重放窗口。旧 server session 最近一分钟仍有有效包时不替换；packet ID 即将溢出时重新生成 client session ID 并清空旧接收窗口。
-- TUN 与 SOCKS5 的响应预算分别传入封装层，外层 wire 上限为 65,507 字节；超限不截断交付。关闭清空窗口并关闭底层 transport，不新增协议后台任务。
-- 上游组选择使用同一次建链快照；DIRECT 使用已准备的代理服务器地址，代理上游保留逻辑服务器地址，不重新执行业务路由。
-
-## 依赖与日志边界
-
-官方 Git revision 固定为 `ab388c7466d21f979430e33cc9ef10e22fb05955`，关闭默认 features，仅启用 `aead-cipher-2022`；registry `shadowsocks-crypto` 为 `0.8.0`。没有协议源码补丁或研究目录 path 依赖。
-
-仅允许 `shadowsocks → shadowsocks-crypto → aws-lc-rs → aws-lc-sys` 链使用 AWS-LC，来源、features 与反向依赖边由 `check tls-dependencies` 校验。TLS / REALITY 保持既有 rustls + ring；额外 AWS-LC 消费者、FIPS 和 2022-extra features 被拒绝。
-
-官方库的 `log` 调用可能包含密钥或流量。启用 SS feature 时，通过 `log/max_level_off` 和 `release_max_level_off` 编译关闭该 facade 的全部日志；Cargo feature 合并意味着这也关闭同一依赖图中其他 `log` 调用，并非仅按 SS target 过滤。VCore 自身使用的 `tracing` 不受影响。上游 Debug 类型不通过公开适配器暴露。
-
-UDP 重放窗口代码派生自官方项目中的 MIT 实现；来源、版权及完整许可文本见 [源码文件头](../src/outbound/shadowsocks/packet_window.rs)。发布时仍须审计目标平台的实际链接依赖图。
-
-## 已知限制与验收边界
-
-1. **上游 padding 风险未修补。** 锁定官方源码在空 TCP 首写、空 UDP payload 等路径扩展 padding 长度但没有显式初始化字节，存在把残留缓冲内容传给可解密对端的风险。原样复用并不等于该风险已修复；普通 echo 测试不能代替安全结论。
-2. SS 2022 首次固定头不足单次读取长度时，官方库按协议的探测防护要求拒绝；不改为无限等待或 `read_exact`。
-3. 当前 mihomo 服务端只暴露单 PSK。AES EIH 数据面通过独立测试中继逐层校验并剥离 1 / 2 层身份头，再把未解密的业务流量交给 mihomo；TCP/UDP 和错误身份拒绝均已执行。这不是 mihomo 原生 EIH 服务端支持，也不证明任意服务商的身份链部署。
-4. 三算法活动 TCP/UDP Stop、绑定失败回滚、独立测速返回后的 socket 回收已在 macOS 验证。全协议组合压力与目标设备仍有独立门槛，见 [验收矩阵](acceptance.md)。
diff --git a/docs/socks5-proxy.md b/docs/socks5-proxy.md
deleted file mode 100644
index a8f7065..0000000
--- a/docs/socks5-proxy.md
+++ /dev/null
@@ -1,44 +0,0 @@
-# SOCKS5 代理入站
-
-SOCKS5 与 HTTP、TUN 共用规则、DNS、代理组和出站图；入口不提前解析业务域名。协议遵循 [RFC 1928](https://www.rfc-editor.org/rfc/rfc1928) 与 [RFC 1929](https://www.rfc-editor.org/rfc/rfc1929) 的 CONNECT、UDP ASSOCIATE 和用户名密码协商。
-
-## 配置与监听
-
-- 顶层 `socks-port` 省略或为 0 时关闭，1–65535 时绑定同端口 TCP 与 UDP。
-- HTTP、SOCKS5、TUN 至少启用一个；纯 SOCKS5 可以独立运行，并使用代理组 Controller、DNS 和 GeoData。
-- `authentication`、`allow-lan` 与 HTTP 共用。默认仅回环且免认证；非空认证必须恰好一项 `user:password`，用户名和密码分别为 1–255 UTF-8 字节，按首个冒号分隔。共享必须配置认证，凭据和共享开关必须有启用的 HTTP 或 SOCKS5 入口消费。
-- `ipv6: false` 只绑定 IPv4；true 时增加独立的 IPv6-only socket。仅系统明确不支持该地址族时可省略 IPv6，其余错误使启动失败。
-- 所有入站和 Controller 完成绑定后才开始服务。HTTP/SOCKS5 TCP 端口冲突、必要的 UDP 端口冲突均整体回滚。
-- 用户名密码协商没有传输加密；共享只适合受信任网络。Controller 的回环和 Bearer 认证不随共享开关改变。
-
-## TCP 与授权
-
-仅 SOCKS5；按当前配置选择免认证或用户名密码方法，不降级绕过已配置认证。握手使用精确读取，保留紧随 CONNECT 的业务字节。认证失败不建立上游。
-
-CONNECT 将 IPv4、IPv6 或域名目标交给共享 Dispatcher；只有上游建立成功才返回成功，拒绝、不可达、超时等使用 SOCKS5 回复码。双向转发支持半关闭，每方向复制缓冲区 4 KiB。
-
-## UDP 关联
-
-- 一个成功协商的 TCP 控制连接拥有一个关联；未授权 UDP 不创建状态或上游。
-- 请求的源 IP 必须为未指定地址或 TCP peer IP，不能把代理用于其他来源。回复使用接受到的 TCP 连接的具体本地 IP 和配置端口，即使监听器绑定通配地址，也不返回不可达的通配 relay。
-- 用 TCP peer IP、IPv6 接口作用域（scope）与客户端 UDP 源端口识别关联；作用域取自 TCP peer，不从客户端请求推断。请求源端口为 0 时，首个合法且成功入队的同作用域 UDP 包学习端口；同 IP、同作用域至多存在一个尚未学习端口的关联，新的歧义请求被拒绝。同 IP、同作用域的不同明确端口可并存，同端口不能重复授权；不同作用域的相同链路本地地址互不串包。
-- 每个关联可转发多个目标，分别经过共享路由；回包保留出站提供的实际远端地址。
-- 非零保留位、分片、非法地址、零目标端口和超长报文被丢弃；无效包不学习端口、不延长空闲时间。
-- TCP EOF、错误、停止或关联过期撤销授权。源端口可以重新授权，但旧任务不能删除新关联或发送旧代次回包。
-
-这比 mihomo 的共享 UDP 接收策略更严格：UDP 必须归属于仍然有效的 TCP 控制连接，不因收到任意 UDP 包隐式创建关联。
-
-## 边界与回收
-
-| 项目 | 固定上限 / 策略 |
-| --- | --- |
-| 协商 | 10 秒；方法和用户名/密码各最多 255 字节 |
-| TCP 建链、UDP 建链/单次发送/回包写入 | 15 秒，整个操作随所属连接取消 |
-| 单关联待发队列 | 16 包；满队列丢弃当前包，不阻塞其他客户端 |
-| UDP 入站 wire 大小 | 65,507 字节；接收额外一个 sentinel 字节识别截断/超限 |
-| UDP 回包业务负载 | 保守预留最大 262 字节 SOCKS5 头，最多 65,245 字节；嵌套出站继续逐层计算封装预算 |
-| 关联空闲 / 检查间隔 | 30 秒 / 10 秒；只有成功入队和成功发送的合法回包刷新时间 |
-
-没有全局业务连接或关联数量准入限制。全局 UDP 接收只做有界解析和非阻塞入队，慢建链和写入留在各关联任务。控制连接拥有该任务，Stop 取消并等待全部 TCP 控制、relay 和 UDP 接收任务，返回后监听端口可以重新绑定。TUN 仍使用其独立 MTU 预算；Controller 流量统计不包含 SOCKS5 数据。
-
-独立 `inbound-socks5` feature 可在不启用业务 HTTP 的构建中使用；默认和 TUN 构建包含两个客户端代理入口。验证范围见 [验收矩阵](acceptance.md)。
diff --git a/docs/testing-isolation.md b/docs/testing-isolation.md
new file mode 100644
index 0000000..45c07e5
--- /dev/null
+++ b/docs/testing-isolation.md
@@ -0,0 +1,23 @@
+# 服务端测试隔离规则
+
+自 2026-09-23 起，**后续所有服务端测试均在隔离容器中执行**。本文件是服务端测试部署方式的权威规则，优先于历史脚本和验收记录中的宿主运行说明。
+
+## 范围
+
+- 协议服务端（Mihomo、Xray、V2Ray、Hysteria、Shadowsocks 等）、UDP echo / TCP / HTTP / DNS 测试原站，以及故障注入中的服务端角色，全部容器化。
+- 对照客户端若提供 SOCKS/HTTP 等测试入口，该入口也放在容器中。宿主只运行待测客户端、测试驱动和只读观察工具。
+- 纯内存、编解码、离线配置或 mock 单元测试不属于外部服务端互通测试。不能把宿主网络服务改称 mock 来规避隔离。
+- 尚未完成容器化、容器不可用或平台不支持的服务端用例记为 `BLOCKED` / `NOT RUN`，不得回退到宿主启动。Linux 测试对端不代表 VCore 新增 Linux 产品支持。
+
+## 执行要求
+
+1. 使用本次任务独占、可识别所有权的容器和私有网络。macOS 使用 Apple Container 的 host-only 网络；不发布宿主端口，不改宿主 VPN、路由、DNS 或防火墙。
+2. 协议对端使用官方最新稳定发行二进制，通过官方 `latest` 下载链接获取；不查版本 API、不本地编译、不修改第三方源码、不静默复用旧缓存。镜像使用官方稳定标签，在当次运行记录解析后的 digest。记录容器内实际版本、二进制和下载包校验值。
+3. 保留 Mihomo 回环保护和第三方默认 socket 行为；不能通过关闭保护、放宽数据正确性/超时或重试业务包掩盖失败。
+4. 原站和协议对端的地址必须来自本次容器网络。配置、证书与测试凭据仅放临时目录，fixture 只读挂载，日志保持有界且脱敏。
+5. 注册清理后再启动资源。成功、失败、超时、SIGINT 和部分启动都必须停止并删除本次拥有的容器，检查剩余资源；不得停止或清理其他任务的容器。
+6. 报告分别记录隔离拓扑、真实流量结果、源码身份和清理结果。基础设施/清理失败不能记为互通通过；定向诊断通过不等于阶段签收。
+
+已批准的局部例外：H3/mTLS 测试网关可用官方最新稳定版 `xcaddy` 编译官方最新稳定版 Caddy，再导入隔离容器。保留 go.mod/go.sum、工具版本、构建日志、二进制 hash 和容器内版本；不修改第三方源码、不新增协议 decoder。Caddy 只终结 H3/TLS 并转发 HTTP，XHTTP 会话与 VLESS 解码仍由同一个原生 Xray handler 负责。此例外不允许编译 Mihomo/Xray 等对端，也不把本地构建称为官方预编译产物。
+
+历史宿主测试保留为历史证据，不追改为容器测试。旧脚本即使有 `--container`，若原站或反向服务仍在宿主，也不满足本规则；迁移前不得用于新的服务端验收。
diff --git a/docs/tls-client-fingerprint.md b/docs/tls-client-fingerprint.md
new file mode 100644
index 0000000..b1abb7d
--- /dev/null
+++ b/docs/tls-client-fingerprint.md
@@ -0,0 +1,113 @@
+# TLS 证书与客户端指纹
+
+两个字段相互独立：
+
+| 字段 | 含义 | 接受值 |
+| --- | --- | --- |
+| `fingerprint` | 服务端证书 DER 的 SHA-256 pin | 64 个十六进制字符，可带冒号 |
+| `client-fingerprint` | 客户端 ClientHello 的命名模板 | 下列七值；空串也关闭 |
+
+| 公开值 | 实际模板 |
+| --- | --- |
+| `none` | 关闭命名指纹，不关闭 TLS 或 REALITY 认证 |
+| `chrome` | Chrome133 |
+| `chrome120` | Chrome120（固定） |
+| `firefox` / `firefox120` | Firefox120 |
+| `safari` / `safari16` | Safari16.0 |
+
+节点省略时关闭，显式启用推荐 `chrome`；这是节点级选项，无全局默认。
+大小写敏感，未知名称、`null`、错型全部拒绝；不接受 `chrome133`、`safari16.0`、
+移动端、随机或 PSK/PQ 专用名称。短名只随显式依赖升级和验收变更，不随 OS 自动选择。
+
+## 适用范围
+
+AnyTLS、Trojan、VMess + TLS、VLESS + TLS/REALITY/JLS 使用同一共享连接器。
+TCP、WS、gRPC、HTTP 首包伪装、legacy H2、Vision、XHTTP H1/H2 仍遵守各自的协议约束。
+关闭 TLS 时不能携带该字段。SOCKS5、SS 2022 不接入 TLS 指纹。
+
+XHTTP `download-settings.client-fingerprint` 缺省继承主腿，显式名称覆盖，`none` / 空串清除。
+下载腿即使与主腿使用同一服务器，也拥有独立的 TLS 策略、身份和缓存。
+切换到明文或 H3 前必须显式清除继承的非空 profile；H3 不支持此模板，不回退 H2。
+
+```yaml
+type: vless
+tls: true
+client-fingerprint: chrome
+# fingerprint: # 与 ClientHello 模板独立
+```
+
+## 后端与认证
+
+- 默认验证公开信任链、名称及有效期。叶证书 pin 匹配时以叶证书为显式信任依据，
+ 不再要求公共根、名称或有效期；匹配非叶证书时将其作为信任锚，仍验证叶链、名称和有效期。
+ skip 只跳过常规验证，不能覆盖不匹配的 pin；所有策略仍验证握手签名。
+- 未启用指纹的标准 TLS 和 QUIC 使用 crates.io 官方 rustls + ring，不依赖 rustls fork。
+- 命名指纹的标准 TLS，以及所有 REALITY/JLS，使用 release 分支并由 lockfile 锁定的自有 boring fork。
+- 普通 TLS 两条路径共用同一个 WebPKI 证书验证器和发布信任根；叶 pin、非叶信任锚、
+ 独立验证名、skip 优先级不变。TLS 握手签名仍由各自后端强制验证。
+- VLESS mTLS 继续使用配对的内联 PEM，密钥匹配在使用 IO 前检查；profile 不修改身份。
+- REALITY 仅允许自身临时证书认证，不能混用 pin/skip/mTLS 或降级到普通站点证书。
+- [JLS](vless.md#jls) 使用共享凭据身份和完整原生 TLS1.3，不启用恢复或 PKI 回退；profile 不改变身份。
+- 连接器只包装 Dialer/上游交付的 IO，不解析 DNS、不创建 socket、不绕过平台 protect。
+
+## 四模板边界
+
+模板由 fork 固定密码套件、组/share、签名算法、扩展排列及受限扩展编码。
+
+| 模板 | 主要差异 |
+| --- | --- |
+| Chrome120 | 经典 X25519 share，GREASE/乱序、ECH GREASE、Brotli、条件 padding、旧 ALPS 17513 |
+| Chrome133 | 普通 TLS 与显式混合 REALITY 使用原生 X25519MLKEM768 和 X25519 双 share；新 ALPS 17613，无 padding |
+| Firefox120 | 自有 cipher 顺序、固定扩展顺序、X25519/P-256 双 share，无 GREASE/ALPS/证书压缩 |
+| Safari16.0 | 固定扩展和签名顺序、GREASE、条件 padding、真实 Zlib 解压，模板本身不加 ECH/ALPS |
+
+TLS 版本范围、SNI、ALPN、证书策略、身份和恢复预算仍由节点及传输决定。
+因此名称表示版本固定的 TLS 模板，不承诺完整浏览器行为或所有上下文的逐字节相同。
+最低 TLS1.2；Safari 的 TLS1.0/1.1 声明裁剪，Vision/XHTTP/REALITY 继续强制 TLS1.3。
+普通 Vision/XHTTP 的版本约束同时省略 TLS1.2 cipher 及仅用于旧握手的
+EC point formats、extended master secret、session ticket、renegotiation info 扩展。
+命名 REALITY 则保留模板的 TLS1.2 声明与字段，由原生 REALITY 在 ServerHello 阶段
+拒绝非 TLS1.3 协商；这与关闭命名指纹时的 TLS1.3-only 默认 offer 分开。
+ALPS 仅在实际提供 h2 时发送，不复制 Mihomo 某些 WS 调用中的额外 h2 ALPS。
+classic REALITY 移除 Chrome133 的 ML-KEM group/share，并绑定实际 X25519 私钥；
+Firefox 的额外经典 share 不产生第二份 REALITY 身份。REALITY 仍拒绝 HRR、恢复和 0-RTT。
+
+`reality-opts.support-x25519mlkem768`：默认 false，true 要求实际
+发送且协商 X25519MLKEM768（4588），经典选组即失败，不重试或降级。只兼容 `chrome`
+或关闭命名指纹；后者使用原生混合-only offer，不自动切到 chrome。Chrome120、Firefox120、
+Safari16.0 在配置期拒绝该组合。下载腿继承/整体替换 REALITY 后，再独立验证最终 profile。
+ML-KEM 增强 TLS 密钥交换，REALITY 身份认证仍基于 X25519，不宣称后量子身份认证。
+
+Firefox 的 FFDHE、delegated credentials、record size limit 及 Safari 的模板专用
+cipher 声明不开放新的配置能力；不能真实完成的对端选择明确失败，不静默换模板。
+
+模板不模拟浏览器 HTTP/2 SETTINGS、QUIC 参数，也不会自动启用实际 ECH。
+VLESS 可另行显式配置[静态 ECH](vless.md#静态-ech)：四模板均可使用，届时强制 TLS1.3、
+加入真实 ECH 并关闭恢复；不再声称与未启用 ECH 的历史浏览器模板逐字节相同。
+当前 HTTP 驱动不导入 TLS ALPS 中的应用设置，因此**非空 ALPS 响应明确失败**；
+未协商或协商空设置可用。Brotli/Zlib 解压输出和原生证书消息上限均为 128 KiB；
+超限、截断、错误算法和损坏压缩流失败，不能绕过证书认证。
+
+## 所有权与关闭
+
+节点的 SNI、ALPN、验证策略、mTLS 身份、版本范围、profile 和 SSL 上下文不可变。
+每次独立构造建立独立缓存，clone 只共享同一节点。标准 TLS 的运行时票据总预算为 4；
+TLS 1.3 票据只消费一次，TLS 1.2 会话也计入预算，过期票据清除，零预算关闭恢复。
+非零 TLS1.2 ticket lifetime hint 与原生 session timeout 取较短者；零提示不扩大原生期限。
+Safari16 不声明 TLS1.2 session-ticket 扩展，该版本的恢复使用会话 ID，不能把不存在的
+票据提示当作它的过期时间。TLS1.3 的票据期限已由原生握手收敛。
+握手及应用层 ALPN 策略通过前，暂存票据不会进入节点缓存。REALITY 始终不恢复。
+别名只复用模板，不扩大节点/下载腿缓存归属。冷连接和恢复连接分开验收；VCore 的
+票据策略不同于 Mihomo，恢复 hello 不宣称逐字段相同，也不伪造 PSK/binder。
+
+CloseWrite 刷新 close_notify 最多 5 秒，保留底层连接和读方向；重复关闭幂等，
+关闭后拒绝写入。Vision direct 切换保留同一 TLS 记录边界，先排空明文/刷新密文，
+不向裸流插入外层 TLS alert。XHTTP 仍按其整条逻辑连接关闭契约工作。
+
+## 验证与发布
+
+验证使用真实公开配置、共享连接接口和独占容器内的原生协议对端；
+编解码及纯内存 TLS 测试不启动宿主监听器。命令见 [构建与检查](../scripts/README.md)，
+指纹分层与 golden 比对见 [指纹验证](../tests/fingerprints/README.md)，
+结果的证明范围见 [验收边界](acceptance.md)。设备、性能、体积和发布许可证审查各自独立，
+本地互通或交叉编译不替代这些门禁。
diff --git a/docs/tls-dependencies.md b/docs/tls-dependencies.md
new file mode 100644
index 0000000..b4abacd
--- /dev/null
+++ b/docs/tls-dependencies.md
@@ -0,0 +1,67 @@
+# TLS 依赖与发布
+
+版本、完整 Git revision 和 registry 校验值以 Cargo.toml/Cargo.lock 为准，
+由 `check tls-dependencies` 审核，不在文档复制一份易失效的包清单。
+
+## 来源与后端
+
+| 用途 | 来源 / 约束 |
+| --- | --- |
+| 普通无指纹 TLS、QUIC、共享 WebPKI | crates.io 官方 rustls/tokio-rustls，仅 ring |
+| 命名 ClientHello、REALITY、JLS | 自有 OneXray/boring 的 release 分支，由 lockfile 固定完整已发布 revision |
+| SS 2022 | crates.io shadowsocks 版本依赖，原样官方库，仅 aead-cipher-2022 |
+| Encryption 原语 | 同一 boring 的公共 X25519、ML-KEM、AEAD、AES-CTR；官方 blake3 |
+| 静态 ECH | 官方 hpke，经 rustls 公开 HPKE trait；命名模板使用 boring 既有 ECH 接口 |
+
+boring/tokio-boring/测试用 boring-sys 必须同源、同分支、同 revision；审计拒绝混合提交、
+未批准 revision、其他分支及本机 path/references/rustls Git patch。
+旧 rustls fork 已退役，不是回退或重建来源。分支前移不会自动改变 locked 构建。
+
+AWS-LC 只允许 shadowsocks → shadowsocks-crypto → aws-lc-rs → aws-lc-sys 链；
+不能供 TLS/REALITY 使用。禁止额外消费者、FIPS 和 2022-extra。
+SS 日志抑制与未修补风险见[出站](outbounds.md#shadowsocks-2022)。
+
+## 身份与原生接口
+
+VCore 负责策略和受控 IO，BoringSSL 拥有握手字节、认证状态和临时秘密。
+REALITY 使用同一 X25519 临时密钥生成 share、ECDH 和 session ID；连接级验证器
+检查临时证书和 CertificateVerify，失败清零并终止。普通 TLS 与 REALITY 使用不同
+不可变连接器，不热换身份、不保留第二个 REALITY 后端或降级开关。
+模板与 ALPS 限制见[TLS 指纹](tls-client-fingerprint.md)，线格式见[REALITY](reality-wire-protocol.md)。
+
+JLS hook 认证真正的 hello，保留 TLS 签名/Finished/记录保护；不可重试失败前清零，
+非阻塞重试保留必要材料。其内部 ShadowTLS hook 依赖不等于支持 ShadowTLS。
+Restls 不支持。所有 fork 补丁由 feature 控制，原始 BoringSSL 子模块不直接改写。
+
+Encryption 的固定文本 context 使用官方 Rust blake3；二进制 context 使用
+[私有薄 FFI](../crates/vcore-blake3-raw/README.md)，包装未修改的官方 C portable 源，
+保留逐文件 hash、许可证及符号隔离，不在构建时下载。自有临时密钥使用 zeroize，
+不承诺擦除配置 String 或第三方全部内部副本。强制 ChaCha 测试入口只在 interop-test。
+
+ECH 不引入第三套 TLS/provider；升级时审查 rustls HPKE/wire enum 接点。
+Brotli/Zlib 解压采用 fork 的受限实现和纯 Rust 依赖，不新增系统 zlib。
+普通 TLS 票据采用原生超时与非零 ticket hint 的较短期限；身份、票据所有权及失败策略
+见[TLS 契约](tls-client-fingerprint.md)。
+
+## 构建与发布
+
+原生构建需要 C/C++、CMake、Perl、libclang，分别验证目标工具链。
+Apple 最终链接需要 libc++（module map 已声明，直接 C 链接需 -lc++）。
+Android 必须随库打包同 ABI/同 NDK 的 libc++_shared.so；只生成 libvcore.so 不证明可加载。
+测试用 boring-sys/foreign-types 仅服务纯内存 peer，不新增生产后端。
+
+发布记录绑定 VCore/boring revision、lockfile hash、registry 校验值、BoringSSL 子模块/
+补丁 hash、toolchain、架构、产物 hash 和签名。许可证审核覆盖实际 release graph、
+boring MIT/Apache-2.0、BoringSSL 随源通知及 Android C++ runtime，不能只看 crate license。
+
+## 升级与回退
+
+1. 选择官方最新稳定依赖；fork 同步上游并先完成普通 TLS 回归。
+2. fork 变更先发布至 release；同次修改 manifest、lockfile 和依赖审计的批准 revision。
+3. 重跑确定性向量、ClientHello/share/证书/签名、恢复/取消/期限及受影响容器数据面；
+ 分别验证 AnyTLS 标准 TLS 和 REALITY/JLS，不能互相抵扣。
+4. 在没有相邻 fork 目录的干净 checkout 执行 locked fetch、离线测试、相关平台构建和
+ 原生消费者。全目标 --no-run 只是编译，网络 peer 仍遵守[隔离规则](testing-isolation.md)。
+5. 按[验收边界](acceptance.md)完成对应设备/安装门禁并保存当次证据。
+
+回退使用新提交恢复仍可获取的已验证 lockfile，不恢复已退役 fork。
diff --git a/docs/tun-icmp-dns.md b/docs/tun-icmp-dns.md
index 5855a52..0e9c8b2 100644
--- a/docs/tun-icmp-dns.md
+++ b/docs/tun-icmp-dns.md
@@ -157,6 +157,14 @@ DNS 和普通 UDP 响应使用不同队列，但共享 netstack UDP 入站接收
普通非 DNS UDP 关联不设固定总数，采用代次感知所有权、30 秒空闲超时和 10 秒清理周期。只有成功入队的请求或响应刷新活动时间。
+## IP-only协议与独立测速接点
+
+公共`ResolutionContext`仅在协议必须取得IP地址的边界解析业务目标或逻辑上游；原始`Destination`保持不变，HTTP Host、TLS SNI和路由仍使用逻辑名称。代理endpoint的prepare bootstrap与该运行期解析分离，不递归使用尚未建立的同一出口。当前静态ECH不查询DNS；动态ECH及其可选宿主bootstrap入口尚未实现，不属于当前Invoke v5。
+
+Running Session上下文仅弱引用本session的RuntimeDns，使用上文nameserver/policy与出口；未绑定、DNS关闭、上游不可达或session已停止时明确失败，不调用系统resolver兜底。IP字面量仍执行端口/地址族政策。解析共享同一次建链期限，Stop取消当前及后续查询；在进入可能等待自身的singleflight之前拒绝同名递归依赖，嵌套依赖深度最多32层。不会因为DNS经代理出口就无条件禁止整个图。
+
+独立`measureDelay`使用测量生命周期的受控bootstrap resolver，仅在IP-only边界解析域名；不创建Running Session、RuntimeDns或DNS监听服务，也不改变现有endpoint准备流程。通用 IP-only connector 覆盖最终节点和 `dialer-proxy` 上游的受控解析、期限与取消。该公共接点继续供 packetaddr 等必须 IP 的消费者使用；通用机制测试不替代各协议的实际数据闭环。
+
## 不支持
- 真实 ICMP 转发、ICMP error、Traceroute、ICMP 选路规则或 ICMP 测速；
diff --git a/docs/tun-platform.md b/docs/tun-platform.md
index e413d47..5e147f0 100644
--- a/docs/tun-platform.md
+++ b/docs/tun-platform.md
@@ -52,7 +52,7 @@ Windows 使用 `Windows.Networking.Vpn` 回调，不使用文件描述符或适
- 数据帧为 `u16` 长度加 `1..=1500` 字节数据。写端最多合并 8 个已经就绪的帧，读端使用 64 KiB 缓冲区并逐帧校验；
- EOF、截断、超限、任务异常和进程退出都会停止当前会话。
-完整契约见 [Windows VPN 平台边界](windows-vpn.md) 和 [Windows 会话运行时](windows-session-runtime.md)。
+完整契约见 [Windows VPN 平台边界](windows-vpn.md) 和 [Windows 会话运行时](windows-vpn.md)。
## MTU 与结构上限
diff --git a/docs/vless.md b/docs/vless.md
new file mode 100644
index 0000000..58fbcc7
--- /dev/null
+++ b/docs/vless.md
@@ -0,0 +1,184 @@
+# VLESS 出站
+
+`outbound-vless` 使用共享 Dialer、上游图及 TLS/REALITY/JLS，不创建独立 socket 或系统 DNS。
+本文定义选定能力集，不承诺上游所有扩展；字段与版本以 [config.yaml](config.yaml) 为准。
+
+## 配置与传输
+
+`type: vless`，`server`、非零 `port` 和标准格式 `uuid` 必填。`udp` 默认 false；`network` 默认 `tcp`，`tls` 默认 false。`encryption` 省略、空或 `none` 关闭该层；其他值见下文。`flow` 省略、空或 `xtls-rprx-vision`。未知字段、null、错型或不匹配的传输选项失败，不隐式迁移配置。
+
+- TCP/WS/gRPC/HTTP 首包伪装/legacy H2 可明文或标准 TLS。TLS 支持 1.2/1.3，TCP 默认不发送 ALPN，WS 默认 `[http/1.1]`，gRPC/H2 默认 `[h2]`。有序 ALPN 保留且必须包含传输要求值；标准 TLS 检查协商结果。`servername` 优先显式值、WS Host 去端口、server；不会改变拨号地址。TLS 关闭时禁止安全选项。
+- 标准 TLS 支持 `skip-cert-verify`、SHA-256 `fingerprint`、独立 `name-cert-verify`；沿用共享证书验证器的叶 pin / 非叶信任锚优先级。`certificate` / `private-key` 是配对的内联 PEM，解析或密钥不匹配在 IO 前失败，禁止文件路径。REALITY 不能混用这些标准证书策略。
+- `client-fingerprint` 使用 [TLS 指纹](tls-client-fingerprint.md)的七值/四模板，适用于 TCP 上的标准 TLS/REALITY（含 Vision 和 XHTTP H1/H2），与证书 pin 独立；`none` / 空串关闭，H3 拒绝已启用的 profile。
+- WS 的 ED 支持默认头、自定义头或路径（上限 2048 字节）。`v2ray-http-upgrade` 开启升级后裸流；`v2ray-http-upgrade-fast-open` 必须与前者一起启用，只允许默认 ED 头。fast-open 提前发协议首包但仍等待合法 101，拒绝不返回连接成功。
+- gRPC 接入 `grpc-user-agent`（默认 `grpc-go/1.36.0`）、非负秒数 `ping-interval`（0 不主动 PING），以及三项池阈值。空闲连接总是复用；max-connections>0 时按连接上限/min-streams 扩容，否则按 max-streams 复用阈值扩容。三项全零归一 max-connections=1；显式正 max-connections 与正 max-streams 互斥。阈值不是硬流数上限。物理连接归节点所有，关闭逻辑流不会杀死兄弟流；复用不重选上游组。
+- gRPC 不新增业务流/建链数量额度；每个物理连接一个自有驱动，每个等待调用只保留自身 future、取消与原期限，不派生队列任务。每节点最多保留 4 条空闲连接，多余空闲连接退役且不影响活动流。空闲 PING 等待 ACK 最多 15 秒，节点 Stop 取消并 join 所有驱动。
+- `network: xhttp` 支持 H1/H2 明文、TLS1.3 或 REALITY，H3 仅标准 TLS1.3。请求字段、独立下载腿、池与版本选择见 [XHTTP](xhttp.md)。H3 的物理 UDP 仍由原 Dialer/上游图创建。
+- `smux` 以独立的 h2mux/smux v1/yamux 承载逻辑 TCP/UDP；不是 XUDP。only-tcp、调度及关闭边界见 [XHTTP 与 sing-mux](xhttp.md)。
+- Vision 仅允许 `network: tcp`，要求 TLS 1.3/REALITY 或 Encryption；UDP 仅 XUDP。启用 Encryption 后外层 TLS 可省略，存在时仍保持独立认证。配置阶段拒绝 WS/gRPC/HTTP/H2/XHTTP、raw/packetaddr、sing-mux 与 Vision 的组合，包括未启用业务 UDP 但显式选错编码。ECH 和附加安全封装仍拒绝。
+- Vision 请求不自动降级；对端用户不支持 Vision 时业务失败。Mihomo 服务端允许为 Vision 用户显式配置空 flow，这属于普通 VLESS 模式，不是错误 flow 的拒绝用例。
+
+## REALITY
+
+`reality-opts.support-x25519mlkem768` 为非 null 布尔值，默认 false。true 强制真实混合
+TLS 密钥交换，服务端选择经典组时失败；可用于主连接和 XHTTP 独立下载连接。
+仅 `chrome` 或未命名 profile 兼容，模板及下载继承约束见 [TLS 指纹](tls-client-fingerprint.md)。
+
+## JLS
+
+共享凭据身份认证仍使用完整原生 TLS 1.3，不是 skip 或失败后裸流回退。
+
+### 配置
+
+- 对象出现即启用，两项必须都是非空字符串，各 1–65,535 个 UTF-8 字节，不 trim。
+ 主连接不接受空对象；未知字段、null、错型、缺项及超限在 IO 前拒绝。
+- 必须 `tls: true`。同一腿不能混用 REALITY、标准证书策略或客户端证书；
+ ECH、其他安全封装、Vision 和 HTTP/3 也不属于此组合。
+- `servername`、有序 ALPN、传输必需 ALPN 与已支持的七值/四模板
+ `client-fingerprint` 沿用共享配置，不增加全局默认或别名。
+- `download-settings.jls-opts` 缺省继承整个身份；非空对象必须完整替换两项，
+ `{}` 清除，不能按叶继承另一个身份的密码。其他下载字段独立覆盖。
+- 切换下载安全模式须显式清除旧身份及冲突证书策略；设置新对象不会自动删除旧对象。
+ 两腿仍必须汇入同一个原生 XHTTP handler 的会话表。
+
+### 认证与所有权
+
+锁定的自有 boring JLS hook 认证实际 ClientHello/ServerHello，由原生 TLS
+完成 transcript、CertificateVerify、Finished 和记录保护。共享凭据替代 WebPKI
+身份，但不会跳过握手签名或 Finished。普通 TLS 证书、错误凭据、篡改握手、
+TLS 1.2 和 HRR 都不能满足 JLS；失败不发伪装 HTTP 探测、不重发业务、不回退 DIRECT。
+模板保留 TLS 1.2 的声明下限，实际成功协商始终必须 TLS 1.3。
+
+每条腿的连接器身份不可变；不启用 TLS 恢复、PSK 或 early data。自有凭据副本
+使用清零容器，原生临时材料按握手/失败清理；不宣称擦除所有配置 String 副本。
+连接器只包装既有 Dialer/上游交付的受控 IO，不创建 resolver、socket、后台任务
+或额外连接池。建链期限、取消、ALPN 检查和同步 Stop 继承现有运行时。
+
+JLS 继续承载 TLS 记录，CloseWrite 沿用共享 TLS 有界关闭；XHTTP 保持整流关闭。
+Encryption 位于外层传输内，身份彼此独立，不能由单层成功推断组合验收。
+
+## 静态 ECH
+
+仅显式静态 ECHConfigList；保护内层 ClientHello 名称，不隐藏 IP、外层名称或流量形态。
+无动态 HTTPS RR/bootstrap、公共 DNS 后备或自动更新。
+
+### 配置
+
+```yaml
+ech-opts:
+ enable: true
+ config: "<服务端提供的标准 Base64 ECHConfigList>"
+```
+
+- 仅标准 TLS，内层 `servername` 必须是 DNS 名，实际只协商 TLS 1.3。
+ 同腿不能与 REALITY、JLS 或 Vision 混用；可与 VLESS Encryption、证书策略、
+ mTLS 和既有传输组合。命名指纹仍只用于 TCP TLS，H3 仍拒绝命名指纹。
+- `enable` 默认 false。启用必须同时提供非空 `config`；不查询 HTTPS RR，
+ 不接收 `query-server-name`，没有公共 DNS 后备或自动更新配置。
+- `config` 是标准带填充 Base64，不是 URL、文件路径或 PEM。解码后的完整
+ ECHConfigList 最多 65,537 字节，仍受整份配置 256 KiB 上限限制。
+- 支持 ECH 版本 `0xfe0d`、X25519/HKDF-SHA256，以及 AES-128-GCM、
+ AES-256-GCM、ChaCha20-Poly1305。预检选取第一个双方后端均支持的条目，
+ 保留其原始编码；未知版本或不兼容条目可跳过，无兼容条目、畸形长度、非法
+ public_name 或不支持的必需扩展在 IO 前失败。不能依赖 BoringSSL 静默忽略。
+- `{}` / `{enable: false}` 清除 ECH。关闭时不允许携带非空 config，以免
+ 用户认为给出的隐私配置已经生效。null、未知字段、错型均拒绝；诊断不回显配置。
+
+`xhttp-opts.download-settings.ech-opts` 缺省继承整个主腿对象；出现时整对象替换，
+不逐字段合并，替换密钥须同时写 `enable: true`。显式 `{}` 可仅清除下载腿 ECH。
+切换到 REALITY/JLS/明文必须显式清除继承的 ECH，以及其他冲突的证书身份。
+两腿仍须汇聚到同一原生 XHTTP handler；各自独立建立和认证外层安全连接。
+
+### 后端与失败边界
+
+无指纹 TCP TLS 与 H3 使用官方 rustls + ring，通过公开 HPKE trait 接入官方
+`hpke`；命名指纹使用锁定的自有 boring fork 既有 ECH 接口。本次不修改
+第三方 TLS 实现，不恢复 rustls fork，也不扩展 Shadowsocks 的 AWS-LC 例外。
+
+两后端都必须真正接受 ECH 才交出业务连接。rustls QUIC 的 ECH 拒绝作为原生
+握手错误传播，H3 在握手完成前不发送 HTTP 请求；TCP 另检查 accepted 状态。
+不把 GREASE 当真实 ECH，不自动采用 retry config，不重拨、不回放业务，也不
+降级为未加密 ClientHello 的成功连接。错误或轮换后的旧密钥需要宿主更新配置。
+
+静态 ECH 连接禁用 TLS 会话恢复和 0-RTT；XHTTP/gRPC 的已认证物理连接仍可在
+原节点内复用。不同节点、主/下载腿、配置替换和后续运行实例不会共享 TLS 票据。
+本层只包装调用方提供的 IO，不创建 resolver、socket、后台任务或全局缓存。
+
+正常 ECH 接受后沿用内层证书名称、pin 和 mTLS 策略。拒绝分支不返回业务成功，
+也不能发送客户端证书。boring 使用原生 outer-name override，按外层名称和默认
+WebPKI 验证拒绝连接，不沿用内层 pin/skip。rustls 的公共 verifier 没有独立的
+ECH-rejection 回调：沿用配置的证书策略后仍由原生状态机强制失败；不获取或使用
+retry config。该拒绝证书路径不宣称与 Mihomo 完全相同，但不放宽业务成功门槛。
+
+## Encryption
+
+`mlkem768x25519plus.{native,xorpub,random}.{1rtt,0rtt}.[.…][.…]`。
+key 为无填充 URL-safe Base64，解码后 32 字节 X25519 或 1184 字节 ML-KEM-768
+公开密钥，可组成有序链；非法 ML-KEM 编码在 IO 前拒绝，X25519 低阶共享密钥
+在握手失败关闭。最多 16 个 key、128 个 padding 三元组和 65,536 字节配置串。
+
+padding 采用 Mihomo 的 `概率-下界-上界` 三元组，交替表示字节长度、毫秒间隔。
+首组概率至少 100、两端至少 35；长度上界累计不超过 65,553。
+概率按 Mihomo 的包含边界比较，区间上界排除；相等/倒序端点允许。
+缺省为 `100-111-1111.75-0-111.50-0-3333`，等待受原建链期限及取消控制。
+
+所有密钥交换、AEAD 和 CTR 使用既有官方原语，AES-256-GCM / ChaCha20-Poly1305
+根据 CPU 选择，不增加用户算法选项。每节点一个恢复票据；`1rtt` 不复用，
+`0rtt` 在票据有效时恢复，过期改为新握手。错误票据/认证失败不会自动重发业务。
+节点缓存互相隔离，旧连接失败不清除新一代票据，Stop 清空缓存且禁止再次插入。
+
+该层位于外层传输内、VLESS 请求头外；WS/HTTPUpgrade/HTTP 的 initial data 是
+Encryption 握手字节，不能提前发送明文 VLESS 请求头。XHTTP 主/下载腿汇聚为
+一条逻辑流后只执行一次 Encryption。普通 Encryption 关闭与 Mihomo CommonConn
+一致，flush 后关闭整条逻辑流，不承诺半关闭尾包；不关闭复用池中的兄弟流。
+
+Vision 在独立的 Encryption 记录边界切换：先排空已认证明文，再绕过 AEAD；
+已有外层 TLS 保留，random 模式保留记录头 CTR，不重置计数器。
+进入 direct 后，native/xorpub 继承底层 CloseWrite 并保留读取方向；random 对齐
+Mihomo 不可替换的 XorConn，仍整流关闭。未进入 direct 时三种外观均整流关闭。
+验收只覆盖实际列举的组合，不由单层成功推断整个组合或设备通过。
+
+## Vision
+
+Vision padding、TLS 记录过滤和读写切换状态独立管理。内层非 TLS / TLS 1.2 只结束 padding，保持外层加密；识别支持的内层 TLS 1.3 协商后，分别发送/接收 direct 标记才切到裸流。每次发送最多暂存 8 KiB 一帧，接收逐段处理 u16 长度，不按声明长度无限分配。非法 UUID/命令或截断关闭 IO；取消读取保留帧进度。
+
+外层 TLS 使用公开 rustls 或 boring 接口及同一记录边界适配器；每次最多读一个 TLS 记录，不在识别切换标记前吞入后续裸流。切换读取前排空已解密明文，切换写入前 flush 外层密文；VCore 不访问 TLS 私有内存布局。direct 关闭不向裸流插入外层 close-notify；未切换时保留共享 TLS 的有界关闭语义。
+
+## UDP
+
+`packet-encoding` 默认 **xudp**，与既有 VCore 行为一致：
+
+| 配置 | 线上语义 | 目标 |
+| --- | --- | --- |
+| 省略 / `xudp` | VLESS CommandMux + 共享 XUDP 帧 | 每包携带 IP / 域名 |
+| `none` | VLESS CommandUDP + 两字节长度 | 固定首包目标，后续换目标失败 |
+| `packetaddr` / `packet` | CommandUDP 到原生约定地址，长度帧内再带地址 | IP-only，域名经受控 ResolutionContext 解析 |
+
+`none` 是 VCore 的显式 raw 拼写，不是对 Mihomo 同名字段的兼容承诺。原生约定地址不做本地 DNS。UDP 443 不额外过滤。
+
+raw/packetaddr 每关联只拥有一个已建流，首次发送前已固定物理上游选择和建链期限；等待首包不会重新选择组或重启期限。packetaddr 不调用系统 resolver：运行期使用本 Running Session DNS，独立测速使用受控 bootstrap。
+
+收发预算独立与调用方预算取交集。raw/XUDP payload 受 u16 上限约束，packetaddr 另扣 IPv4 7 / IPv6 19 字节地址头（未解析域名按较大开销预检）。raw/packetaddr 接收 wire 最多 65,537 字节，逐段读取，合法超接收预算的整包丢弃。对端可能有更小容量，原生夹具预算不能冒充生产协议上限。
+
+部分发送取消立即关闭 IO，不允许接着发送半帧；接收取消保留帧进度。非法帧或响应头关闭关联，不切换编码、不回退 DIRECT。显式 close 后不能恢复收发。
+
+## 关闭和期限
+
+VLESS 响应头允许延迟到业务响应前；TCP 不等待它才允许发送请求。读取、首次响应和传输握手共用原建链期限，错误或超时释放 IO。UUID 和业务目标不进入 Debug/诊断。
+
+普通 TCP/TLS 按底层 CloseWrite 语义工作；HTTP 首包伪装没有 Mihomo CloseWrite，shutdown 释放整个逻辑流并唤醒读侧。gRPC/H2 结束当前逻辑流，gRPC 的兄弟流与节点池不受影响。XHTTP 上传 EOF/shutdown 关闭整条逻辑连接，包括下载腿；需要完整响应时在关闭前读完。验收分别检查正常完整性和对齐 Mihomo 的关闭行为，不要求所有传输半关闭后都收到尾包。
+
+## 验证边界
+
+所有服务端、原站、DNS 和对照入口遵守[隔离规则](testing-isolation.md)。
+ignored 未执行不计通过；精确组合与源/对端身份在当次报告记录，不拼接旧成绩。
+HTTPUpgrade/fast-open 与 sing-mux 的未列举组合不从单层结果推导。
+
+静态 ECH 的 H3 使用 Xray，packetaddr/sing-mux 使用明确标注的 XHTTP → Mihomo 解码。
+HTTP/H2/扩展 WS 可用 Xray TLS 网关 → V2Ray transport；需 UDP/Encryption 时另由
+Mihomo 解码。网关使用官方 XRAY_BUF_SPLICE=disable，避免下行 raw splice 绕过 TLS；
+不代表 V2Ray 直接支持 ECH。无指纹 JLS/gRPC 及 Safari ECH/gRPC 的官方对照缺口采用
+明确标注的 Chrome 关闭参照；VCore 原配置的数据面单独验证，不声称同配置差分。
+动态 ECH、ShadowTLS、Restls 不支持，配置严格拒绝。
+
+WS + REALITY（普通 WS、HTTPUpgrade、fast-open）的数据及认证使用真实 Mihomo listener；关闭验证采用明确标注的分层参照。当前 Mihomo WS 客户端分支未接入 REALITY，不能作为同组合对照，因此使用标准 TLS 的同种传输客户端关闭基线，并独立验证 REALITY。不得将该结果写成 Mihomo WS + REALITY 客户端互通或同组合差分通过。
diff --git a/docs/windows-session-runtime.md b/docs/windows-session-runtime.md
deleted file mode 100644
index e6c5085..0000000
--- a/docs/windows-session-runtime.md
+++ /dev/null
@@ -1,245 +0,0 @@
-# Windows 会话运行时
-
-Windows package 只有一个主 Application，但每个 VPN 会话仍由独立的完全信任 Session Host 独占完整 VCore 运行时。AppContainer Provider 只负责 Windows VPN 平台资源、原始包转发和失败关闭；系统中不存在 Provider 内嵌运行时的备用路径。
-
-## 参与者与所有权
-
-```text
-前台宿主（完全信任）
- ├─ VCoreInvoke
- └─ VCoreWindowsVpnInvoke
- ├─ Session Snapshot / profile
- └─ ConnectProfileAsync
- │ Windows 激活
- ▼
-vcore-windows-vpn-host.exe + vcore.dll（AppContainer）
- ├─ VpnChannel / 路由 / DNS / 物理网络
- ├─ VpnPacketBuffer / 有界回调队列 / 失败关闭
- └─ FullTrustProcessLauncher
- │ 无参数激活
- ▼
-vcore-windows-session-host.exe
- ├─ 校验不可变 Session Snapshot
- ├─ 可选 Windows session backend / Job Object
- ├─ PreparedCore / RunningCore
- ├─ DNS / 规则 / GeoData / 嗅探器 / select 代理组
- ├─ VLESS / SOCKS5 / AnyTLS / DIRECT
- └─ 运行时 Controller（TUN 流量 / 代理组选择）
- ▲
- └─ 同包控制管道 + 数据管道
-```
-
-| 参与者 | 拥有 | 不拥有 |
-| --- | --- | --- |
-| 前台宿主 | 用户命令、会话记录、UI 状态 | TUN 运行时、包通道、Provider 状态 |
-| Windows 桥接 | Session Snapshot、profile、连接/断开命令 | 数据包、代理流、Session Host 进程 |
-| Session Host | 单次 VCore 运行时、可选 session backend、Controller、GeoData、包客户端 | `VpnChannel`、路由、进程业务配置 |
-| Provider | `VpnChannel`、WinRT 缓冲区、路由、物理绑定、管道服务端、网络监控、Session Host 激活 | YAML、代理图、Controller、GeoData、backend 描述 |
-| SOCKS 服务 | 自身监听器、外层 socket 和绕过策略 | VCore 代理图和 Windows profile |
-
-Session Host 每次连接新建一个进程，不常驻、不复用运行时，也不处理 URI 或 StartupTask。
-
-## 快照与 profile
-
-- Windows 只维护一个同包 `VCore` profile。
-- 桥接先用当前解析器验证 TUN 配置、四个网络地址、全局 VPN policy 和可选 backend，再发布单文件内容寻址 Session Snapshot：
-
- ```text
- vcore-session-v2:<64 lowercase sha256>
- LocalState/vcore/windows/sessions/.json
- ```
-
-- Snapshot revision 2 保存完整 VCore YAML（包括代理组及其 `default-selected`），以及可选的有序 `sessionBackend.processes`；每项只有规范 package-relative executable path 和 argv 数组。
-- token 覆盖 YAML、进程顺序、路径和参数。参数引用的文件由调用方保持存在且不可变，VCore 不读取或摘要其内容。
-- profile custom configuration 是最大 4 KiB 的严格 JSON，包含修订版 4、规范 Session token、顶层 IPv6 开关、TUN/DNS 的 IPv4/IPv6 地址和完整 policy。
-- custom configuration 不包含 YAML、backend 描述、Controller secret、PID 或管道路径。
-- `startVpn` 的四个地址和 `alwaysOn`、`allowLocalNetwork`、`excludedCidrs` 始终严格必填并经过验证；顶层 `ipv6: false` 时，Provider 忽略两个 IPv6 地址，只安装 IPv4 地址、路由和 DNS，并拒绝 IPv6 exclusion。
-- 活动 profile 只有在 token、IPv6 开关、四个地址和 policy 完全相同时才幂等；任何变化都必须先 Stop。
-- 读取 Snapshot 时校验大小、普通文件、reparse point、内容摘要、规范 JSON及每个 executable。
-- TUN 地址、Controller 端口/secret 和 Ping 目标属于运行时字段，不写入用户 RAW YAML。
-
-## 启动顺序
-
-1. 前台宿主调用 `startVpn(configYaml, networkSettings, policy, sessionBackend?)`。
-2. 桥接验证配置、四个地址、policy 和进程描述，发布不可变 Session Snapshot，并把解析后的顶层 IPv6 开关和 policy 写入 profile configuration。
-3. 桥接写入单一 VPN profile 并调用 `ConnectProfileAsync`；它不启动或持有 Session Host。
-4. Windows 激活 AppContainer Provider。
-5. Provider 从 profile configuration 取得权威 token，选择物理网络绑定并准备基础资源。
-6. Provider 清理陈旧会合记录，通过无参数 `FullTrustProcessLauncher` 激活 Session Host。
-7. Session Host 不读取动态命令行参数，等待 Provider 会合记录。
-8. Provider 创建控制/数据管道服务端并原子发布会合记录。
-9. Session Host 严格解析会合记录，把其中的 token 作为候选值，构造限定对象路径并连接两条管道。
-10. Session Host 发送 `SessionHello`；Provider 把候选 token 与 profile token 精确比较后返回 `ProviderHello` 和不可变物理绑定。
-11. Session Host 验证 `ProviderHello` 回传同一 token，之后才读取 Snapshot；若存在 backend，则用一个 kill-on-close Job Object 按顺序启动全部进程。
-12. Session Host 准备并启动完整 VCore 运行时、静态代理组状态和 Controller。
-13. Session Host 确认受管进程尚未退出后返回 `RuntimeReady`。
-14. Provider 调用 `StartWithMainTransport` 并启动失败关闭监视器。
-15. 连接成功后，桥接向前台宿主返回当前系统 VPN 状态。
-
-任一步失败都必须关闭包通道并收敛为 Disconnected，只返回有界脱敏错误；未完成握手的 Session Host 最多等待 15 秒后退出。
-
-Session Host 的路径读取和启动失败日志必须在同一次 WinRT 初始化周期内完成；`RoUninitialize` 后不能再次查询缓存的 `ApplicationData` factory。没有 package identity 的裸启动快速、安全退出，不进入握手、不启动 backend，也不回退到普通用户数据目录。
-
-## 会合记录
-
-`LocalState/vcore/windows/rendezvous.json` 最大 4 KiB：
-
-```json
-{
- "protocolVersion": 1,
- "snapshotToken": "vcore-session-v2:...",
- "objectPath": "AppContainerNamedObjects\\S-1-15-2-...",
- "controlLeaf": "VCore.Vpn.Control.v1",
- "dataLeaf": "VCore.Vpn.Data.v1"
-}
-```
-
-- Provider 是唯一发布者和清理者；
-- 使用同目录暂存文件和原子重命名；
-- 只接受规范 token、AppContainer 相对路径和固定 leaf；
-- 非普通文件、reparse point、超限或未知字段都会失败关闭；候选 token 与 profile token 的绑定只在双向握手中完成；
-- 握手完成后删除，新连接前清理断开状态下的陈旧记录。
-
-## 控制协议
-
-```text
-u32 大端序 JSON 长度
-严格 UTF-8 JSON
-```
-
-- 单帧最大 16 KiB；
-- DTO 拒绝未知字段、错误版本和错误顺序；
-- 错误码最大 128 字节，脱敏信息最大 4 KiB；
-- 不传 YAML、Controller secret、SOCKS 凭据、日志或 Invoke 请求。
-
-版本 1 消息：
-
-```text
-SessionHello { version, snapshotToken }
-ProviderHello { version, snapshotToken, physicalBinding }
-RuntimeReady { version }
-RuntimeFailed { version, code, redactedMessage }
-Stop { version, packetCounters }
-Stopped { version, packetCounters }
-```
-
-启动超时 15 秒，有序停止确认超时 10 秒。活动包流没有空闲超时或 heartbeat。
-
-## 数据协议
-
-每个方向只有一个写端：
-
-```text
-u16 大端序包长
-1..=1500 字节原始 IP 包
-```
-
-- EOF、截断、零长度、超限和帧格式错误会停止当前会话；
-- 合法帧中的非法 IP 包由原始包解析器局部丢弃；
-- wire v1 不包含 batch envelope、方向字节、校验和或压缩；
-- 写端只等待首包，然后最多排空 7 个已经位于现有有界队列中的包；
-- 不等待计时器或未来数据，低流量单包立即发送；
-- 两端读端使用 64 KiB 缓冲区并逐帧校验；
-- 编码缓冲区在任务内复用，单次最多写入 `8 × 1502` 字节。
-
-## 回调队列
-
-Provider 两侧容量均为 256：
-
-```text
-Encapsulate
- -> 复制包
- -> try_send 入站队列
- -> 包写端
-
-数据读端
- -> 有界出站队列
- -> 空到非空唤醒
- -> Decapsulate 排空
-```
-
-回调不等待管道 I/O。队列满时只丢当前包并计数。Session Host 的 `WindowsTunIo` 使用同样的有界通道并接入 `TunRuntime`；流量统计继续按原始 IP TUN 边界计算。
-
-## 物理网络绑定
-
-Provider 选择并持有：
-
-- 适配器 GUID；
-- profile 和 network identity；
-- 可用地址族从非 link-local 地址中选出的源 IP 和非零接口索引；
-- 独立于源地址选择保留的全部去重 on-link prefixes，包括 link-local。
-
-Session Host 只消费这份不可变绑定。每个非回环 socket 必须同时设置源地址和接口选项。只有配置中显式使用 `127.0.0.0/8` 范围内的 IPv4 字面量或 `::1` 的本地出站可以跳过；物理代理服务器的域名在准备阶段解析到任何回环地址都会失败关闭。地址族缺失、bind 失败或 setsockopt 失败时，当前连接失败关闭。
-
-Provider 订阅网络变化，等待 2 秒消抖后复验适配器、选定源地址、全部 on-link prefixes 和 identity。任一变化就停止会话，不迁移 socket、不重选网卡、不自动回退。
-
-## Windows session backend
-
-`sessionBackend` 可以省略；存在时包含 `1..=8` 个进程。每个进程只声明：
-
-```json
-{
- "executableRelativePath": "bin\\proxy-core.exe",
- "arguments": ["run", "--mode", "vpn"]
-}
-```
-
-- executable 必须是 package installed location 内不经过 reparse point 的规范 `.exe` 相对路径；
-- argv 项数、单项大小、总大小和最终 UTF-16 command line 均有界；
-- 不经过 shell，不展开环境变量，工作目录固定为 package installed location；
-- Session Host 使用 `CreateProcessW(CREATE_SUSPENDED)`，先加入设置了 `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE` 的 Job，再恢复主线程；
-- 所有进程都是关键进程；任一退出都会停止 VCore、终止同 Job 中的其余进程并使 Provider 失败关闭；
-- Stop 先停止 VCore，再终止 Job，确认活动进程归零后才返回 `Stopped`；
-- 第一版不提供 port、UDP、readiness、heartbeat、restart、environment、working directory 或单进程控制；
-- `RuntimeReady` 只表示进程仍存活且 VCore 已启动，不表示进程内部协议已就绪。
-
-## Controller 与本地 SOCKS
-
-- Controller 由 Session Host 监听完全信任的回环地址；
-- `RuntimeReady` 前必须完成绑定，失败则连接失败；
-- 前台宿主持有配置中的端口和 secret，并调用 `GET /traffic`、`GET /group`、`GET /group/{name}`、`GET /proxies/{name}` 或 `PUT /proxies/{name}`；
-- 配置代理组与 Controller 时 secret 必填并保护全部路由；仅有 TUN 流量 Controller 时 secret 仍可省略；
-- 代理组选择属于 Session Host 中实际 Running Session 的内存状态，不经过 Windows bridge、Provider 控制管道或 Session Snapshot 写回；
-- 成功切换只影响之后新建的物理 TCP、UDP 和 DNS transport，不迁移既有连接、UDP association、DNS 状态或 TCP pool，也不执行自动 failover；
-- 宿主如需跨 VPN session 保留选择，必须自行持久化，并在下次 `startVpn` 的 YAML 中注入对应 `default-selected`；
-- 前台宿主退出后 Controller 和运行时继续，重新启动后恢复查询；
-- Stop 关闭 Controller，销毁本次代理组选择；下一会话重新采用 YAML 初始选择并从零计数；
-- 回环 SOCKS5 是普通 VCore 出站；其服务可以由外部宿主管理，也可以恰好运行在 session backend 中，但 VCore 不从 backend 描述推断端口或 readiness；
-- 单个 SOCKS 流失败不停止 VPN。
-
-## 生命周期
-
-| 事件 | 结果 |
-| --- | --- |
-| 前台宿主退出 | Provider、Session Host 和运行时继续 |
-| 前台宿主重启 | 以系统 profile 为权威恢复状态和 Controller 查询 |
-| Provider 退出 | Windows 清理 VPN，Session Host 因 EOF 退出 |
-| Session Host 退出 | Job 清理受管进程，Provider 失败关闭并停止 VPN |
-| 任一受管进程退出 | 停止 VCore和其余受管进程，Provider 失败关闭 |
-| 物理网络变化 | 消抖后停止 VPN |
-| 管道非法或 EOF | 停止当前会话 |
-| 显式 Stop | Disconnect -> Stop -> 有界确认 -> channel Stop |
-| 本地 SOCKS 流失败且服务进程仍存活 | 只失败当前流 |
-| Controller 绑定失败 | 启动失败，profile 不进入 Connected |
-| Controller 切换代理组 | 当前 Session Host 原子更新选择；既有 transport 保持原路径 |
-
-桥接不持有或终止 Session Host 进程；启动失败由 Provider 的 Connect 清理路径收敛，显式 Stop 通过系统 profile 断开。
-
-## 安装包契约
-
-```text
-HostApplication.exe
-vcore.dll
-vcore-windows-vpn-host.exe
-vcore-windows-session-host.exe
-[optional package-local managed executables]
-```
-
-- 产物架构与安装包一致，Rust 产物使用静态 CRT；
-- Session Host 不显示在应用列表，不注册 StartupTask、URI 或 VPN background task；
-- Provider activation 来自 `vcore.dll`；
-- Manifest 包含 `networkingVpnProvider` 和 `runFullTrust`；
-- 不使用产品级 loopback exemption；
-- 安装或升级前必须断开活动 VPN，版本必须递增。
-
-当前实测范围和未完成发布门禁见 [验收矩阵](acceptance.md)。
diff --git a/docs/windows-vpn.md b/docs/windows-vpn.md
index 1fb8d76..42d7827 100644
--- a/docs/windows-vpn.md
+++ b/docs/windows-vpn.md
@@ -147,14 +147,6 @@ Provider 是物理网络状态的唯一权威，并订阅 `NetworkStatusChanged`
会合记录只包含协议版本、Session token、相对对象路径和固定管道名称，不包含 YAML、backend 描述、参数、secret、PID、物理绑定或任意文件路径。Provider 是唯一发布者和清理者。
-## 可选 session backend
-
-`startVpn` 可以携带一个只描述进程的 `sessionBackend`。它包含 `1..=8` 个有序项目，每项只有 package-relative `.exe` 路径和 argv 数组。Bridge 把该描述与 VCore YAML 一同发布为 `vcore-session-v2:` Session Snapshot；路径或参数变化会改变 token，活动会话不能热换。
-
-Session Host 为全部进程创建一个设置了 kill-on-close 的 Job Object，使用 suspended create 在进程执行前完成 Job assignment。任一进程退出都会停止 VCore、清理同 Job 进程树并让 Provider 失败关闭；显式 Stop 在 `Stopped` 前完成同样清理。前台宿主退出不影响它们。
-
-第一版只监督进程存活，不包含 port、UDP、协议 readiness、heartbeat、restart、environment 或 working directory。进程仍存活时，本地 SOCKS 或其他业务流失败只影响当前流。
-
## 安装包与 profile
安装包必须包含：
@@ -166,13 +158,13 @@ vcore-windows-vpn-host.exe
vcore-windows-session-host.exe
```
-- manifest 只有一个主 Application，三个可执行参与者相互独立；
+- manifest 只有一个主 Application，三个可执行参与者相互独立；产物架构一致，Rust 使用静态 CRT；
- Session Host 是 `windows.fullTrustProcess` extension，不显示在应用列表，也不注册 StartupTask 或 URI；
- Provider 的 `windows.backgroundTasks` extension 显式使用 `windowsApp + appContainer`；
- Provider activation class 来自 `vcore.dll`；
- 同一 package 只维护一个 `VCore` VPN profile；
- custom configuration 是最大 4 KiB 的严格 JSON，只含修订版 4、Session token、顶层 IPv6 开关、四个网络地址和完整 policy；
-- Session Snapshot 是 `LocalState/vcore/windows/sessions/.json`，覆盖 YAML、可选进程顺序、路径和参数；
+- Session Snapshot 是 `LocalState/vcore/windows/sessions/.json`，revision 2 覆盖完整 YAML、可选进程顺序、路径和参数；读取验证大小、普通文件、reparse point、规范 JSON、摘要和每个 executable。参数引用的文件由宿主保持存在且不可变，VCore 不读取其内容；
- 活动 Session token、IPv6 开关、网络地址或 policy 不同时必须先显式 Stop，不能热切换；
- 安装包更新只能在 VPN 已断开时进行，并要求版本递增。
@@ -192,6 +184,150 @@ vcore-windows-session-host.exe
当前实测范围和未完成平台门禁见 [验收矩阵](acceptance.md)。
+## 参与者与所有权
+
+```text
+前台宿主（完全信任）
+ ├─ VCoreInvoke
+ └─ VCoreWindowsVpnInvoke
+ ├─ Session Snapshot / profile
+ └─ ConnectProfileAsync
+ │ Windows 激活
+ ▼
+vcore-windows-vpn-host.exe + vcore.dll（AppContainer）
+ ├─ VpnChannel / 路由 / DNS / 物理网络
+ ├─ VpnPacketBuffer / 有界回调队列 / 失败关闭
+ └─ FullTrustProcessLauncher
+ │ 无参数激活
+ ▼
+vcore-windows-session-host.exe
+ ├─ 校验不可变 Session Snapshot
+ ├─ 可选 Windows session backend / Job Object
+ ├─ PreparedCore / RunningCore
+ ├─ DNS / 规则 / GeoData / 嗅探器 / select 代理组
+ ├─ 统一出站图
+ └─ 运行时 Controller（TUN 流量 / 代理组选择）
+ ▲
+ └─ 同包控制管道 + 数据管道
+```
+
+| 参与者 | 拥有 | 不拥有 |
+| --- | --- | --- |
+| 前台宿主 | 用户命令、会话记录、UI 状态 | TUN 运行时、包通道、Provider 状态 |
+| Windows 桥接 | Session Snapshot、profile、连接/断开命令 | 数据包、代理流、Session Host 进程 |
+| Session Host | 单次 VCore 运行时、可选 session backend、Controller、GeoData、包客户端 | `VpnChannel`、路由、进程业务配置 |
+| Provider | `VpnChannel`、WinRT 缓冲区、路由、物理绑定、管道服务端、网络监控、Session Host 激活 | YAML、代理图、Controller、GeoData、backend 描述 |
+| SOCKS 服务 | 自身监听器、外层 socket 和绕过策略 | VCore 代理图和 Windows profile |
+
+Session Host 每次连接新建一个进程，不常驻、不复用运行时，也不处理 URI 或 StartupTask。
+
+
+## 启动顺序
+
+1. 前台宿主调用 `startVpn(configYaml, networkSettings, policy, sessionBackend?)`。
+2. 桥接验证配置、四个地址、policy 和进程描述，发布不可变 Session Snapshot，并把解析后的顶层 IPv6 开关和 policy 写入 profile configuration。
+3. 桥接写入单一 VPN profile 并调用 `ConnectProfileAsync`；它不启动或持有 Session Host。
+4. Windows 激活 AppContainer Provider。
+5. Provider 从 profile configuration 取得权威 token，选择物理网络绑定并准备基础资源。
+6. Provider 清理陈旧会合记录，通过无参数 `FullTrustProcessLauncher` 激活 Session Host。
+7. Session Host 不读取动态命令行参数，等待 Provider 会合记录。
+8. Provider 创建控制/数据管道服务端并原子发布会合记录。
+9. Session Host 严格解析会合记录，把其中的 token 作为候选值，构造限定对象路径并连接两条管道。
+10. Session Host 发送 `SessionHello`；Provider 把候选 token 与 profile token 精确比较后返回 `ProviderHello` 和不可变物理绑定。
+11. Session Host 验证 `ProviderHello` 回传同一 token，之后才读取 Snapshot；若存在 backend，则用一个 kill-on-close Job Object 按顺序启动全部进程。
+12. Session Host 准备并启动完整 VCore 运行时、静态代理组状态和 Controller。
+13. Session Host 确认受管进程尚未退出后返回 `RuntimeReady`。
+14. Provider 调用 `StartWithMainTransport` 并启动失败关闭监视器。
+15. 连接成功后，桥接向前台宿主返回当前系统 VPN 状态。
+
+任一步失败都必须关闭包通道并收敛为 Disconnected，只返回有界脱敏错误；未完成握手的 Session Host 最多等待 15 秒后退出。
+
+Session Host 的路径读取和启动失败日志必须在同一次 WinRT 初始化周期内完成；`RoUninitialize` 后不能再次查询缓存的 `ApplicationData` factory。没有 package identity 的裸启动快速、安全退出，不进入握手、不启动 backend，也不回退到普通用户数据目录。
+
+
+## 会合记录
+
+`LocalState/vcore/windows/rendezvous.json` 最大 4 KiB：
+
+```json
+{
+ "protocolVersion": 1,
+ "snapshotToken": "vcore-session-v2:...",
+ "objectPath": "AppContainerNamedObjects\\S-1-15-2-...",
+ "controlLeaf": "VCore.Vpn.Control.v1",
+ "dataLeaf": "VCore.Vpn.Data.v1"
+}
+```
+
+- Provider 是唯一发布者和清理者；
+- 使用同目录暂存文件和原子重命名；
+- 只接受规范 token、AppContainer 相对路径和固定 leaf；
+- 非普通文件、reparse point、超限或未知字段都会失败关闭；候选 token 与 profile token 的绑定只在双向握手中完成；
+- 握手完成后删除，新连接前清理断开状态下的陈旧记录。
+
+
+## 控制协议
+
+```text
+u32 大端序 JSON 长度
+严格 UTF-8 JSON
+```
+
+- 单帧最大 16 KiB；
+- DTO 拒绝未知字段、错误版本和错误顺序；
+- 错误码最大 128 字节，脱敏信息最大 4 KiB；
+- 不传 YAML、Controller secret、SOCKS 凭据、日志或 Invoke 请求。
+
+版本 1 消息：
+
+```text
+SessionHello { version, snapshotToken }
+ProviderHello { version, snapshotToken, physicalBinding }
+RuntimeReady { version }
+RuntimeFailed { version, code, redactedMessage }
+Stop { version, packetCounters }
+Stopped { version, packetCounters }
+```
+
+启动超时 15 秒，有序停止确认超时 10 秒。活动包流没有空闲超时或 heartbeat。
+
+
+## Windows session backend
+
+`sessionBackend` 可以省略；存在时包含 `1..=8` 个进程。每个进程只声明：
+
+```json
+{
+ "executableRelativePath": "bin\\proxy-core.exe",
+ "arguments": ["run", "--mode", "vpn"]
+}
+```
+
+- executable 必须是 package installed location 内不经过 reparse point 的规范 `.exe` 相对路径；
+- argv 项数、单项大小、总大小和最终 UTF-16 command line 均有界；
+- 不经过 shell，不展开环境变量，工作目录固定为 package installed location；
+- Session Host 使用 `CreateProcessW(CREATE_SUSPENDED)`，先加入设置了 `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE` 的 Job，再恢复主线程；
+- 所有进程都是关键进程；任一退出都会停止 VCore、终止同 Job 中的其余进程并使 Provider 失败关闭；
+- Stop 先停止 VCore，再终止 Job，确认活动进程归零后才返回 `Stopped`；
+- 第一版不提供 port、UDP、readiness、heartbeat、restart、environment、working directory 或单进程控制；
+- `RuntimeReady` 只表示进程仍存活且 VCore 已启动，不表示进程内部协议已就绪。
+
+
+## Controller 与本地 SOCKS
+
+- Controller 由 Session Host 监听完全信任的回环地址；
+- `RuntimeReady` 前必须完成绑定，失败则连接失败；
+- 前台宿主持有配置中的端口和 secret，并调用 `GET /traffic`、`GET /group`、`GET /group/{name}`、`GET /proxies/{name}` 或 `PUT /proxies/{name}`；
+- 配置代理组与 Controller 时 secret 必填并保护全部路由；仅有 TUN 流量 Controller 时 secret 仍可省略；
+- 代理组选择属于 Session Host 中实际 Running Session 的内存状态，不经过 Windows bridge、Provider 控制管道或 Session Snapshot 写回；
+- 成功切换只影响之后新建的物理 TCP、UDP 和 DNS transport，不迁移既有连接、UDP association、DNS 状态或 TCP pool，也不执行自动 failover；
+- 宿主如需跨 VPN session 保留选择，必须自行持久化，并在下次 `startVpn` 的 YAML 中注入对应 `default-selected`；
+- 前台宿主退出后 Controller 和运行时继续，重新启动后恢复查询；
+- Stop 关闭 Controller，销毁本次代理组选择；下一会话重新采用 YAML 初始选择并从零计数；
+- 回环 SOCKS5 是普通 VCore 出站；其服务可以由外部宿主管理，也可以恰好运行在 session backend 中，但 VCore 不从 backend 描述推断端口或 readiness；
+- 单个 SOCKS 流失败不停止 VPN。
+
+
## 官方 API
- [`IVpnPlugIn`](https://learn.microsoft.com/uwp/api/windows.networking.vpn.ivpnplugin)
diff --git a/docs/xhttp.md b/docs/xhttp.md
new file mode 100644
index 0000000..c641ec0
--- /dev/null
+++ b/docs/xhttp.md
@@ -0,0 +1,105 @@
+# XHTTP 与 VLESS sing-mux
+
+XHTTP/sing-mux 使用严格字段与类型；未知、null、无效或被忽略的组合在 IO 前拒绝。
+REALITY、JLS、静态 ECH 的身份规则见 [VLESS](vless.md)，实际验证边界见[验收说明](acceptance.md)。
+
+## HTTP 版本和连接模式
+
+`network: xhttp` 使用现有 Dialer、上游图、保护接口与 SecurityClient，不另建系统解析器或裸 socket。`alpn: [http/1.1]` 选择 H1；空列表、`[h2]` 或包含 H1/H2 的列表选择 H2；只有独占 `[h3]` 选择 H3。不会静默降级 HTTP 版本。
+
+H1/H2 可使用明文、标准 TLS 1.3、REALITY（经典默认、显式混合模式）或 JLS。H3 必须使用标准 TLS 1.3，不允许同腿明文、REALITY 或 JLS。QUIC 收发走受控数据报，上游有效预算小于 1200 字节即拒绝，不绕开代理、protect 或接口绑定；路径 MTU 探测关闭。
+
+`xhttp-opts.mode` 接受 `auto`（默认）、`packet-up`、`stream-up`、`stream-one`。auto 在 REALITY 无下载配置时选择 stream-one，有下载配置时选择 stream-up，其余选择 packet-up。stream-one 是一条双工 POST，不允许 `download-settings`；其余模式以同一会话 ID 关联上传与下载。`path` 默认 `/`，`host` 显式非空优先，否则使用该腿 servername/server；IPv6 authority 使用方括号。主腿与下载腿的 host 均禁止 userinfo（`@`）。
+
+## 请求字段
+
+区间字段均为字符串 `"N"` 或 `"N-M"`，不接受数字、负数、倒置区间、空串或溢出。每次采样保持在闭区间内。
+
+| 字段 | 默认及约束 |
+| --- | --- |
+| `headers` | 字符串 map；最多 100 项 / 8 KiB。禁止 Host、定界/逐跳头、CRLF、大小写重复及与生成字段冲突。值不进入 Debug |
+| `no-grpc-header` | false；true 关闭流式请求的 application/grpc，packet-up 不接受 true |
+| `x-padding-bytes` | `"100-1000"`，1–4096 |
+| `x-padding-obfs-mode` | false：固定 Referer 中的 `x_padding`、queryInHeader、repeat-x |
+| `x-padding-placement` | 混淆开启时必填：queryInHeader/header/query/cookie |
+| `x-padding-key` | 混淆 queryInHeader/query/cookie 时必填；header 不使用此字段 |
+| `x-padding-header` | 混淆 header/queryInHeader 时必填合法头名；其他位置不使用 |
+| `x-padding-method` | repeat-x；开启混淆后也可 tokenish，按 HPACK 编码后的长度生成 |
+| `uplink-http-method` | POST，也接受 PUT/PATCH/DELETE；不将 GET 或 OPTIONS 用于上传 |
+| `session-placement` / `session-key` | path（不填写 key）；header 默认 X-Session，query/cookie 默认 x_session |
+| `session-table` | 空：32 字符随机 hex；uuid：标准 UUID v4；或预定义/自定义去重 ASCII 字符表 |
+| `session-length` | 字符表模式默认 `"16-32"`，1–128；全部长度构成的命名空间至少 2^31。空表/uuid 不接受显式长度 |
+| `seq-placement` / `seq-key` | 仅 packet-up；path，或 header 默认 X-Seq、query/cookie 默认 x_seq |
+| `uplink-data-placement` | body，auto 归一 body；header/cookie 仅用于 packet-up |
+| `uplink-data-key` | header/cookie payload 必填，body 不接受 |
+| `uplink-chunk-size` | header/cookie 默认 `"0"` 自适应；显式区间 64–8192。自适应 header 3072–4096、cookie 2048–3072 |
+| `sc-max-each-post-bytes` | packet-up，`"1000000"`，1–16 MiB；这是 POST 上限，不是预分配缓冲大小 |
+| `sc-min-posts-interval-ms` | packet-up，`"30"`，0–60000 且最大值须为正；允许 `"0-N"`，不允许纯零 |
+
+session/sequence 均支持 path/query/header/cookie。键使用至多 64 字节的 HTTP 安全 token，禁止互相冲突以及覆盖 padding、payload 或既有 query/header。字符表预定义值包括 `ALPHABET`、`Alphabet`、`alphabet`、`BASE36`、`base36`、`Base62`、`HEX`、`hex`、`number`。
+
+路径遵循 Mihomo：session 或 sequence 任一放在 path 时补尾斜杠，否则保留显式路径。原生 Xray 的 handler 始终补尾斜杠；因此与 Xray 互通且两项均不在 path 时，须显式配置带尾斜杠的路径（例如 `/proxy/`）。这是对端路径配置差异，不通过修改 VCore 的默认规范化规则解决。
+
+header/cookie payload 使用无填充 Base64URL，并按实际请求预算拆块；完整请求（URI、生成字段和自定义头）不超过 16 KiB / 128 项。业务数据按有界块处理，不把整个 POST 限额、对端声明或业务流读入无界 Vec。
+
+packet-up 在发送间隔内聚合小块写入，而不是把每个 write 变成一个 POST。最多保留一个待发送批次和一个在途批次，每批最多 64 KiB，并与本连接采样的 POST 上限取较小值；头部 payload 仍按请求预算拆分。write 完成只表示数据已进入有界缓冲，flush 等待对应 POST 确认；计时器无需调用方再次读写即可发送。shutdown 立即尝试 flush 未发送批次，卡住的 POST 仍受一秒上限控制。计时器/上传任务归节点所有，Stop 同步等待。
+
+## 独立下载腿
+
+`download-settings` 缺省和 `{}` 不等价：存在即启用独立下载连接/池，但仍共用一次 VLESS 握手、会话 ID 和建链上下文。两腿必须汇聚到**同一个原生 XHTTP handler 的会话表**；两个独立 listener 不能构成共享会话。
+
+可覆盖 `server/port/tls/servername/alpn/host/path/headers`、`client-fingerprint`、普通 TLS 的 `skip-cert-verify/name-cert-verify/fingerprint/certificate/private-key/ech-opts`、`reality-opts`、`jls-opts` 和 `reuse-settings`。
+
+- 缺省叶字段继承主腿。headers 是整体替换，`{}` 清空；显式空 host 恢复下载认证名/server 推导。
+- `skip-cert-verify: false` 必须覆盖主腿 true；空 name-cert-verify/fingerprint 清除对应 override/pin。
+- `client-fingerprint` 缺省继承，显式名称覆盖，`none` / 空串清除。下载腿切到明文或 H3 前必须清除继承的已启用 profile；它不属于证书策略，不因切换 TLS/REALITY 自动清除。七值/四模板见 [TLS 指纹](tls-client-fingerprint.md)。
+- certificate/private-key 必须配对替换或同时空串清除；PEM 与密钥匹配在 IO 前检查。
+- reality-opts 缺省继承整个对象，`{}` 清除；非空对象必须提供 public-key，short-id 缺省空、support-x25519mlkem768 缺省 false，不按叶合并旧对象。仅提供混合开关不等同空对象，仍须提供 public-key。null 拒绝。
+- jls-opts 缺省继承整个身份，非空对象必须完整替换 username/password，`{}` 清除；同腿与 REALITY 和证书策略互斥，切换时须显式清除旧对象。JLS 仅 H1/H2，实际 TLS1.3，无恢复；完整约束见 [JLS](vless.md#jls)。
+- ech-opts 缺省继承、非空对象整体替换，启用必须同时提供 enable=true 和静态 config；`{}` 清除。仅标准 TLS，可用于 H1/H2/H3。没有动态查询或自动重试；切换到 REALITY/JLS/明文前必须显式清除继承的 ECH。
+- 切换到明文或 REALITY 不会悄悄丢弃继承的证书策略；须显式清除冲突字段。每条腿独立重新校验最终安全配置。
+- 独立地址/端口在 prepare 时分别准备；两腿共享原绝对期限和每个上游组的选择快照，下载失败不会另起超时预算或绕过原图。
+
+## HTTP transport 复用
+
+`reuse-settings` 缺省禁用节点池；`{}` 启用默认池。下载配置缺省继承整个主腿 reuse 对象，显式对象整体替换，未填写项回到零，不逐字段继承。
+
+| 字段 | 语义 |
+| --- | --- |
+| `max-concurrency` | 候选 transport 的并发挑选阈值，默认 `"0"` |
+| `max-connections` | 优先扩到的候选数，默认 `"0"`；全部忙时仍可扩容，不是全节点硬上限 |
+| `c-max-reuse-times` | 复用次数预算，默认 `"0"`；耗尽后不再分配新流 |
+| `h-max-request-times` | 按领取 transport 扣减，默认 `"0"`；不按每个 packet-up POST 扣减 |
+| `h-max-reusable-secs` | 按物理 transport 年龄退役，默认 `"0"`；活动逻辑流继续 |
+| `h-keep-alive-period` | 整数秒；0 为 H2 45 秒 / H3 10 秒，负数禁用，正数指定周期；H1 仅接受 0 |
+
+前五项接受 0–i32::MAX 的字符串区间。h-max-request-times 和 h-max-reusable-secs 只有最大值为零才禁用；例如 `"0-1"` 采样到零仍按零预算或立即到期处理。c-max-reuse-times 则与 Mihomo 一样，采样值为零即不启用该项限制。两腿池与计数独立。已建物理连接保持原上游选择；创建新连接时才使用当前选择。H1 仅复用完整结束的上传请求连接，不复用取消的下载 GET。节点空闲缓存有界；它不构成业务流数量额度。
+
+## VLESS sing-mux
+
+节点级 `smux` 接受 enabled、protocol、max-connections、min-streams、max-streams、padding、only-tcp。enabled 默认 false；protocol 默认 h2mux，也支持 smux v1/yamux。计数是 0–i32::MAX 整数；正 max-connections 与正 max-streams 互斥。padding、only-tcp 默认 false。Vision 与启用的 sing-mux 互斥。
+
+空闲物理会话优先复用；max-connections>0 分支按连接数量与 min-streams 扩容，否则按 max-streams 阈值复用。max-connections=max-streams=0 时 min-streams 归一为 8，但不会将其解释为所有调度分支的硬额度。单流关闭不关闭兄弟流，节点 Stop 才取消和等待所有自有驱动。
+
+每条逻辑流的状态字节沿用该次建链的绝对期限；读取前先检查超时，状态已缓冲也不例外。
+物理连接复用不重置期限；状态已确认后的业务读取不受原建链期限限制。
+
+smux 单流 shutdown 先等待已接受帧写入并 flush，再安排 FIN；h2mux 同样等待数据
+到达上游 IO 的 flush 边界再 reset。节点 Stop 或 Drop 可取消待写，不承诺异常终止交付。
+
+yamux 的内部资源边界是单物理连接累计分配 64 个流后退役；旧流继续，新请求另建连接，空闲即回收。该边界避免逻辑取消与库内 reset 回收不同步时误关兄弟流，不是全节点额度，详见 [资源策略](runtime-resource-policy.md)。
+
+sing-mux 的外层是普通 VLESS TCP 到约定目标，**不是 VLESS CommandMux/XUDP**。only-tcp=false 时 UDP 使用 mux 的逐包地址格式，经受控解析处理域名；true 时保留所选 raw/XUDP/packetaddr 编码。`udp: false` 始终禁止业务 UDP。padding 覆盖握手及最初 16 个物理写入帧；接收增量解析和丢弃 padding，不按声明长度无限分配。
+
+## 关闭、安全与验收边界
+
+XHTTP 按 Mihomo 整条逻辑连接关闭：shutdown 先尝试送完已接受的上传，再取消下载，
+所有模式的待决上传最多等待一秒；超时或节点 Stop 可以取消，异常终止不承诺交付。
+H1/H2 flush 等待已接受的 payload 到达所供应 IO 的 flush 边界；H3 flush 等待上传任务
+写入 QUIC，shutdown 进一步等待该请求上传的 QUIC 确认，再释放物理连接租约。
+这些等待不依赖下载响应。需要完整回复的应用必须在关闭前读完；不承诺 TCP 半关闭
+后继续收到尾包。复用只延长物理 transport 生命周期，不改变单个逻辑连接的关闭范围。
+
+H3 的 QUIC 驱动、数据报适配器和后台任务归节点所有。Stop 先执行有界关闭交换，再取消/join 内部任务和上游 IO，不把 Drop 或“等一会儿资源消失”当作完成屏障。
+
+H1/H2 原生验证优先使用官方 latest Mihomo；H3 使用官方 latest Xray。不被 Xray 直接解码的 packetaddr/sing-mux 使用明确标注的 Xray XHTTP → Mihomo VLESS 分层拓扑；mTLS 使用已批准的 xcaddy/Caddy H3 网关，后端仍是同一个 Xray handler。分层成功不改写直接对端失败。所有服务端与原站在隔离容器中，配置和私钥不入 Git；原生数据、公共入口、资源、跨平台构建和阶段签收分别记录。
diff --git a/example/windows-uwp/README.md b/example/windows-uwp/README.md
index 8d73b8b..c3b7dab 100644
--- a/example/windows-uwp/README.md
+++ b/example/windows-uwp/README.md
@@ -181,7 +181,7 @@ if (response != nullptr) {
VCore 会校验 YAML、发布 `vcore-session-v2:` 内容寻址 Session Snapshot，并把 token、解析后的顶层 IPv6 开关、四个地址和 policy 写入最大 4 KiB 的 profile custom configuration。调用方不要自行创建另一个 `VpnPlugInProfile` 或维护第二份 Snapshot。
-需要让 Session Host 同会话监督 package-local 进程时，可以额外提交 `sessionBackend.processes`；每项只有 `executableRelativePath` 和 `arguments`。第一版不管理端口、UDP、readiness 或进程业务配置，完整契约见 [Windows 会话运行时](../../docs/windows-session-runtime.md)。本 demo 不携带 backend。
+需要让 Session Host 同会话监督 package-local 进程时，可以额外提交 `sessionBackend.processes`；每项只有 `executableRelativePath` 和 `arguments`。第一版不管理端口、UDP、readiness 或进程业务配置，完整契约见 [Windows 会话运行时](../../docs/windows-vpn.md)。本 demo 不携带 backend。
## Manifest 契约
@@ -253,6 +253,6 @@ broker 负责 JSON bridge、命令串行化和结果回传。UWP UI 不接触 YA
详细内部契约见：
- [`../../docs/windows-vpn.md`](../../docs/windows-vpn.md)
-- [`../../docs/windows-session-runtime.md`](../../docs/windows-session-runtime.md)
+- [`../../docs/windows-vpn.md`](../../docs/windows-vpn.md)
- [`../../docs/invoke-api.md`](../../docs/invoke-api.md)
- [`../../docs/acceptance.md`](../../docs/acceptance.md)
diff --git a/include/module.modulemap b/include/module.modulemap
index 0d6b929..ae1b7cf 100644
--- a/include/module.modulemap
+++ b/include/module.modulemap
@@ -1,4 +1,5 @@
module LibVCore {
header "vcore.h"
+ link "c++"
export *
}
diff --git a/readme/README.ru.md b/readme/README.ru.md
index da22cfc..619942f 100644
--- a/readme/README.ru.md
+++ b/readme/README.ru.md
@@ -4,11 +4,11 @@
English · 简体中文 · Русский
-VCore — независимое клиентское прокси-ядро на Rust, не привязанное к конкретному хост-приложению. Через строгую YAML-конфигурацию и Invoke API v5 оно предоставляет граф прокси, статические группы `select`, DNS, правила маршрутизации, GeoData, HTTP/SOCKS5 listeners, плоскость данных TUN и loopback Controller. Внутренняя ревизия схемы конфигурации — 14; она присутствует только в ответе `version` и `buildIdentity`, но не записывается в YAML.
+VCore — независимое клиентское прокси-ядро на Rust, не привязанное к конкретному хост-приложению. Через строгую YAML-конфигурацию и Invoke API v5 оно предоставляет граф прокси, статические группы `select`, DNS, правила маршрутизации, GeoData, HTTP/SOCKS5 listeners, плоскость данных TUN и loopback Controller. Внутренняя ревизия схемы конфигурации — 27; она присутствует только в ответе `version` и `buildIdentity`, но не записывается в YAML.
## Возможности
-- Исходящие подключения: VLESS + XHTTP + TLS/REALITY, SOCKS5 CONNECT/UDP ASSOCIATE, AnyTLS TCP/UoT и DIRECT.
+- Исходящие подключения: [VLESS TCP/WS/gRPC/HTTP/H2/XHTTP, TLS/REALITY и Vision](../docs/vless.md), SOCKS5 CONNECT/UDP ASSOCIATE, AnyTLS TCP/UoT, Shadowsocks 2022, [Trojan TCP/UDP через TLS/WS/gRPC](../docs/outbounds.md#trojan), [VMess AEAD через TCP/WS/gRPC/HTTP/H2](../docs/outbounds.md#vmess-aead), [Hysteria2 TCP/UDP, управление скоростью, Salamander и смена портов](../docs/outbounds.md#hysteria2) и DIRECT.
- Цепочки прокси: `dialer-proxy` образует ориентированный ациклический граф произвольной длины. Если узел A указывает на B, физический путь имеет вид `client -> B -> A -> target`.
- Группы прокси: статические группы `select` сохраняют порядок участников; участниками могут быть конкретные узлы, вложенные группы, `DIRECT` и `REJECT`. Выбор текущей session можно менять через Controller. `dialer-proxy` принимает узел или группу; DIRECT в группе верхнего уровня подключается к заранее разрешённому серверу текущего узла.
- Маршрутизация: последовательно применяются `DOMAIN`, `DOMAIN-SUFFIX`, `DOMAIN-KEYWORD`, `GEOSITE`, `GEOIP`, `IP-CIDR`, `IP-CIDR6`, `DST-PORT`, `NETWORK` и завершающее правило `MATCH`.
@@ -17,6 +17,7 @@ VCore — независимое клиентское прокси-ядро на
- Listeners: HTTP CONNECT/forward с аутентификацией и маршрутизацией каждого запроса, потоковыми телами, Keep-Alive и Upgrade; SOCKS5 CONNECT и UDP ASSOCIATE с авторизацией через TCP. По умолчанию доступ локальный без аутентификации; для LAN требуется общая пара имени пользователя и пароля.
- GeoData: VCore управляет `geosite.dat` и `geoip.dat` в `dataDir/geodata`, загружает их по запросу и может обновлять через цепочку прокси.
- Измерение задержки: `measureDelay` принимает за вызов 1–5 конфигураций node-only, использует до пяти частных worker и сохраняет порядок входных данных в результатах.
+- TLS: независимый pin сертификата и четыре необязательных [шаблона ClientHello](../docs/tls-client-fingerprint.md); [VLESS JLS](../docs/vless.md#jls) сохраняет полную аутентификацию TLS. [Статический ECH](../docs/vless.md#静态-ech) использует явную конфигурацию основного и download-соединения VLESS, без динамических DNS-запросов или отката при ошибке.
## Конфигурация
@@ -72,6 +73,8 @@ Authorization: Bearer
`GET /traffic` возвращает одноразовый TUN snapshot `up/down/upTotal/downTotal`. Конечные точки групп читают и изменяют выбранного прямого участника статической группы `select`; успешное изменение влияет только на новые физические TCP-, UDP- и DNS-transports текущей session. Оно не переносит существующие соединения, UDP associations, состояние DNS или pooled TCP transports и не выполняет автоматический failover. Controller, управляющий группами, требует один Bearer secret для всех маршрутов и может работать без TUN. Подробности — в [`docs/controller-api.md`](../docs/controller-api.md).
+Аутентифицированная сессия Hysteria2 сохраняет выбранный upstream при смене портов. Замена socket в той же QUIC-сессии не считывает выбор группы заново; новый выбор применяется только к новой аутентифицированной сессии.
+
## Платформы
| Платформа | Плоскость данных | Статус |
@@ -93,7 +96,7 @@ packet queue 256
ordinary event / UDP response 128
DNS ingress / DNS response 128 / 128
TCP buffer 32 KiB per direction
-TLS / XHTTP buffer 64 KiB
+rustls / XHTTP buffer 64 KiB
DNS typed cache 256 entries
DNS opaque cache 64 entries / 256 KiB
GeoData allocation capacity 8 MiB
@@ -105,22 +108,11 @@ TCP sessions, обычные UDP associations, half-open connections, outbound h
## Документация
-- [Оглавление документации](../docs/README.md)
-- [Контракт конфигурации](../docs/config.yaml)
+- [Documentation index](../docs/README.md)
+- [Configuration](../docs/config.yaml)
- [Invoke API](../docs/invoke-api.md)
-- [HTTP proxy inbound](../docs/http-proxy.md)
-- [SOCKS5 proxy inbound](../docs/socks5-proxy.md)
-- [AnyTLS outbound](../docs/anytls.md)
-- [Клиентский протокол REALITY V1](../docs/reality-wire-protocol.md)
-- [Зависимость rustls REALITY и требования к выпуску](../docs/rustls-reality-release.md)
-- [Runtime Controller](../docs/controller-api.md)
-- [ICMP и DNS в TUN](../docs/tun-icmp-dns.md)
-- [Правила и assets GeoData](../docs/geodata.md)
-- [Платформенный слой TUN](../docs/tun-platform.md)
-- [Граница платформы Windows VPN](../docs/windows-vpn.md)
-- [Runtime сессии Windows](../docs/windows-session-runtime.md)
-- [Политика ресурсов runtime](../docs/runtime-resource-policy.md)
-- [Матрица приёмки](../docs/acceptance.md)
+- [Build and test](../scripts/README.md)
+- [Acceptance boundaries](../docs/acceptance.md)
## Пример
@@ -130,7 +122,7 @@ TCP sessions, обычные UDP associations, half-open connections, outbound h
```bash
cargo fmt --all -- --check
-cargo test --all-features --all-targets
+uv run --project scripts --locked vcore-scripts check core --profile debug
cargo clippy --locked --all-features --lib --bins -- -D warnings
cargo test --manifest-path crates/vcore-netstack/Cargo.toml --all-targets
cargo clippy --manifest-path crates/vcore-netstack/Cargo.toml --all-targets -- -D warnings
@@ -158,7 +150,8 @@ uv run --project scripts --locked vcore-scripts build windows
- [smoltcp](https://github.com/smoltcp-rs/smoltcp), [clash-rs](https://github.com/Watfaq/clash-rs) и [netstack-smoltcp](https://github.com/automesh-network/netstack-smoltcp): userspace IP stacks и TUN netstacks.
- [windows-rs](https://github.com/microsoft/windows-rs), [UWP VPN Plugin Sample](https://github.com/microsoft/UwpVpnPluginSample), [wireguard-uwp-rs](https://github.com/luqmana/wireguard-uwp-rs), [Maple](https://github.com/YtFlow/Maple) и [YtFlowCore](https://github.com/YtFlow/YtFlowCore): Windows VPN, активация WinRT и packet flow.
- [Xray-core](https://github.com/XTLS/Xray-core), [Mihomo](https://github.com/MetaCubeX/mihomo) и [Leaf](https://github.com/eycorsican/leaf): прокси-протоколы, маршрутизация, архитектура TUN и interoperability references.
-- [rustls](https://github.com/rustls/rustls): TLS-зависимость и upstream сопровождаемого VCore REALITY fork.
+- [rustls](https://github.com/rustls/rustls): TLS без fingerprint, QUIC и общая проверка сертификатов WebPKI.
+- [boring](https://github.com/cloudflare/boring) / [BoringSSL](https://boringssl.googlesource.com/boringssl/): именованные профили TLS ClientHello и расширение classic REALITY в собственном fork VCore.
## Лицензия
diff --git a/readme/README.zh_CN.md b/readme/README.zh_CN.md
index 37b7188..334dab0 100644
--- a/readme/README.zh_CN.md
+++ b/readme/README.zh_CN.md
@@ -4,11 +4,11 @@
English · 简体中文 · Русский
-VCore 是独立且不绑定特定宿主应用的 Rust 客户端代理 core。它通过严格 YAML 配置和 Invoke API v5 提供代理图、静态 `select` 代理组、DNS、规则、GeoData、HTTP/SOCKS5 listener、TUN 数据面与回环 Controller。内部配置 schema revision 为 14；revision 只出现在 `version` 响应和 `buildIdentity` 中，不写入 YAML。
+VCore 是独立且不绑定特定宿主应用的 Rust 客户端代理 core。它通过严格 YAML 配置和 Invoke API v5 提供代理图、静态 `select` 代理组、DNS、规则、GeoData、HTTP/SOCKS5 listener、TUN 数据面与回环 Controller。内部配置 schema revision 为 27；revision 只出现在 `version` 响应和 `buildIdentity` 中，不写入 YAML。
## 能力
-- Outbound：VLESS + XHTTP + TLS/REALITY、SOCKS5 CONNECT/UDP ASSOCIATE、AnyTLS TCP/UoT、DIRECT。
+- Outbound：[VLESS TCP/WS/gRPC/HTTP/H2/XHTTP、TLS/REALITY 与 Vision](../docs/vless.md)、SOCKS5 CONNECT/UDP ASSOCIATE、AnyTLS TCP/UoT、Shadowsocks 2022、[Trojan TCP/UDP（TLS/WS/gRPC）](../docs/outbounds.md#trojan)、[VMess AEAD（TCP/WS/gRPC/HTTP/H2）](../docs/outbounds.md#vmess-aead)、[Hysteria2 TCP/UDP、带宽、Salamander 与端口跳跃](../docs/outbounds.md#hysteria2)、DIRECT。
- 代理链：`dialer-proxy` 组成任意长度的有向无环图；节点 A 指向 B 时，物理路径为 `client -> B -> A -> target`。
- 代理组：静态 `select` 组保留有序成员，可包含具体节点、嵌套组、`DIRECT` 与 `REJECT`；当前 session 的选择可通过 Controller 实时修改。`dialer-proxy` 可引用节点或组；上游组的 DIRECT 连接当前节点预解析的服务器。
- 路由：顺序执行 `DOMAIN`、`DOMAIN-SUFFIX`、`DOMAIN-KEYWORD`、`GEOSITE`、`GEOIP`、`IP-CIDR`、`IP-CIDR6`、`DST-PORT`、`NETWORK` 和最终 `MATCH`。
@@ -17,6 +17,7 @@ VCore 是独立且不绑定特定宿主应用的 Rust 客户端代理 core。它
- Listener：HTTP CONNECT/forward，逐请求认证与选路，支持流式正文、Keep-Alive 和 Upgrade；SOCKS5 CONNECT 与 TCP 授权的 UDP ASSOCIATE。默认本机免认证，局域网共享强制使用一组共用账号密码。
- GeoData：VCore 管理 `dataDir/geodata` 下的 `geosite.dat` 和 `geoip.dat`，按需求加载并可通过代理链后台更新。
- 测速：`measureDelay` 单次接收 1–5 份 node-only 配置，使用最多五个私有 worker，结果保持输入顺序。
+- TLS：独立证书 pin 与四种可选 [ClientHello 模板](../docs/tls-client-fingerprint.md)；[VLESS JLS](../docs/vless.md#jls)保留完整原生 TLS 认证。[静态 ECH](../docs/vless.md#静态-ech)接受显式的 VLESS 主/下载腿配置，不执行动态 DNS 查询或失败回落。
## 配置
@@ -72,6 +73,8 @@ Authorization: Bearer
`GET /traffic` 返回一次 TUN `up/down/upTotal/downTotal` snapshot。代理组端点读取或修改静态 `select` 组的当前直接成员；成功切换只影响当前 session 后续新建的物理 TCP、UDP 与 DNS transport，不迁移既有连接、UDP association、DNS 状态或 TCP 连接池，也不自动故障转移。Controller 管理代理组时，全部路由必须共用一个 Bearer secret，并且可以不启用 TUN。详见 [`docs/controller-api.md`](../docs/controller-api.md)。
+已认证的 Hysteria2 会话在端口跳跃期间保留上游选择；同一 QUIC 会话替换物理 socket 不重新读取组选择，只有新建认证会话才使用新选择。
+
## 平台
| 平台 | 数据面 | 状态 |
@@ -85,42 +88,16 @@ Windows 不使用 fd 模拟层。Provider 只拥有 `VpnChannel`、buffer、rout
## 资源边界
-当前 TUN profile 保留局部结构边界，不按业务 flow 总数做固定 admission：
-
-```text
-raw packet / MTU 1,500 bytes
-packet queue 256
-ordinary event / UDP response 128
-DNS ingress / DNS response 128 / 128
-TCP buffer 32 KiB per direction
-TLS / XHTTP buffer 64 KiB
-DNS typed cache 256 entries
-DNS opaque cache 64 entries / 256 KiB
-GeoData allocation capacity 8 MiB
-```
-
-Windows 按 `StartWithMainTransport` 要求宣告 1,400 字节 L3 MTU；1,500 字节仍是跨平台解析上限。
-
-TCP session、普通 UDP association、half-open、outbound handshake 和 active DNS transport 按需创建；bounded queue、每流 buffer、wire/parser size、timeout、idle cleanup 和 cache 继续提供结构安全。iOS 35/45 MiB 仅为 best-effort 优化观测，不改变生命周期结果。
+使用局部队列、缓冲、解析上限、期限与所有者取消，不设置全局业务流准入数量。
+共享上限见[资源策略](../docs/runtime-resource-policy.md)，专用预算见协议契约；内存遥测不改变生命周期结果。
## 文档
-- [文档索引](../docs/README.md)
-- [配置协议](../docs/config.yaml)
+- [Documentation index](../docs/README.md)
+- [Configuration](../docs/config.yaml)
- [Invoke API](../docs/invoke-api.md)
-- [HTTP 代理入站](../docs/http-proxy.md)
-- [SOCKS5 代理入站](../docs/socks5-proxy.md)
-- [AnyTLS 出站](../docs/anytls.md)
-- [REALITY V1 客户端协议](../docs/reality-wire-protocol.md)
-- [rustls REALITY 依赖与发布要求](../docs/rustls-reality-release.md)
-- [运行时 Controller](../docs/controller-api.md)
-- [TUN ICMP 与 DNS](../docs/tun-icmp-dns.md)
-- [GeoData 规则与资产](../docs/geodata.md)
-- [TUN 平台层](../docs/tun-platform.md)
-- [Windows VPN 平台边界](../docs/windows-vpn.md)
-- [Windows 会话运行时](../docs/windows-session-runtime.md)
-- [运行时资源策略](../docs/runtime-resource-policy.md)
-- [验收矩阵](../docs/acceptance.md)
+- [Build and test](../scripts/README.md)
+- [Acceptance boundaries](../docs/acceptance.md)
## 示例
@@ -130,7 +107,7 @@ TCP session、普通 UDP association、half-open、outbound handshake 和 active
```bash
cargo fmt --all -- --check
-cargo test --all-features --all-targets
+uv run --project scripts --locked vcore-scripts check core --profile debug
cargo clippy --locked --all-features --lib --bins -- -D warnings
cargo test --manifest-path crates/vcore-netstack/Cargo.toml --all-targets
cargo clippy --manifest-path crates/vcore-netstack/Cargo.toml --all-targets -- -D warnings
@@ -158,7 +135,8 @@ VCore 的依赖、维护中的 fork、公开 API/协议参考、架构参考与
- [smoltcp](https://github.com/smoltcp-rs/smoltcp)、[clash-rs](https://github.com/Watfaq/clash-rs) 与 [netstack-smoltcp](https://github.com/automesh-network/netstack-smoltcp)：用户态 IP stack 与 TUN netstack。
- [windows-rs](https://github.com/microsoft/windows-rs)、[UWP VPN Plugin Sample](https://github.com/microsoft/UwpVpnPluginSample)、[wireguard-uwp-rs](https://github.com/luqmana/wireguard-uwp-rs)、[Maple](https://github.com/YtFlow/Maple) 与 [YtFlowCore](https://github.com/YtFlow/YtFlowCore)：Windows VPN、WinRT activation 与 packet flow。
- [Xray-core](https://github.com/XTLS/Xray-core)、[Mihomo](https://github.com/MetaCubeX/mihomo) 与 [Leaf](https://github.com/eycorsican/leaf)：代理协议、路由、TUN 架构与互操作参考。
-- [rustls](https://github.com/rustls/rustls)：TLS 依赖与 VCore 维护的 REALITY fork 上游。
+- [rustls](https://github.com/rustls/rustls)：未启用指纹的 TLS、QUIC 与共享 WebPKI 证书验证。
+- [boring](https://github.com/cloudflare/boring) / [BoringSSL](https://boringssl.googlesource.com/boringssl/)：命名 TLS ClientHello profile 与 VCore 自有 fork 中的 classic REALITY 扩展。
## License
diff --git a/scripts/README.md b/scripts/README.md
index c17276a..35c00bc 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -1,144 +1,141 @@
-# VCore Scripts
+# 构建与验证
-本目录是由 `uv` 管理的 Python 工程，统一提供 VCore 平台构建、静态检查和可选互操作 demo。所有命令都从 VCore 仓库根目录执行：
+所有命令从 VCore 根目录运行，或为 `--project` 显式指定本仓库 scripts。
+Python 工程由 uv/uv.lock 管理，运行时只用标准库；不推断相邻研究仓库。
-```bash
-uv sync --project scripts --locked
-uv run --project scripts --locked vcore-scripts --help
+## 日常检查
+
+```sh
+uv run --project scripts --locked vcore-scripts check core --profile debug
+uv run --project scripts --locked vcore-scripts check core --profile release
+uv run --project scripts --locked vcore-scripts check core --profile features
+uv run --project scripts --locked python -m unittest discover -s scripts/tests
+cargo fmt --all -- --check
+uv run --project scripts --locked ruff check scripts
+uv run --project scripts --locked ruff format --check scripts
+uv run --project scripts --locked vcore-scripts check c-header
+uv run --project scripts --locked vcore-scripts check tls-dependencies
```
-运行时只使用 Python 标准库；`ruff` 是由 `uv.lock` 固定的开发依赖。
+`check core --list` 只显示命令。Debug/Release 只执行明确的纯内存/配置/安全回归；
+features 检查精简构建、准入和完整生产构建，全目标只编译 `--no-run`。
+每条真正执行的 Cargo 测试须有非空成功结果，失败、超时或未 join 均非零退出。
+**不要执行无过滤的 cargo test --all-features --all-targets**：部分历史 fixture 含宿主监听器。
-## 平台构建
+额外生产/测试代码静态检查与 netstack：
-```bash
+```sh
+cargo clippy --locked --features ffi --lib --bins -- -D warnings
+cargo clippy --locked --all-features --all-targets -- -D warnings
+cargo test --locked --manifest-path crates/vcore-netstack/Cargo.toml --all-targets
+cargo clippy --locked --manifest-path crates/vcore-netstack/Cargo.toml --all-targets -- -D warnings
+```
+
+C header 检查只编译 C/C++；TLS 检查审查 resolved graph、provider、来源及批准 revision，
+不是网络互通。边界见 [TLS 依赖](../docs/tls-dependencies.md)。
+
+## 容器互通
+
+```sh
+uv run --project scripts --locked vcore-scripts check protocol-interop --suite integration --list
+uv run --project scripts --locked vcore-scripts check protocol-interop --suite integration --preflight
+uv run --project scripts --locked vcore-scripts check protocol-interop --suite integration
+uv run --project scripts --locked vcore-scripts check protocol-coverage --suite integration --run-dir target/interop/runs/
+uv run --project scripts --locked vcore-scripts check protocol-coverage --catalog-only
+```
+
+可执行容器 suite：vmess、vless、xhttp、hysteria2、security、integration。
+`--case` 可重复、`--protocol` 可筛选；子集只证明实际执行的项目，不能签收整套。
+foundations/trojan 保留基础用例和断言，其旧服务端编排尚未全容器化，不能执行；
+需要 Trojan 互通时用 integration 中的真实容器路径。
+
+文件、用例、事件与报告按协议或验证用途命名，例如 INTEGRATION-PAIR-SS-SS、
+SECURITY-ECH-CHROME；不再提供阶段编号或 --stage 别名。旧报告保持原样，使用
+其记录的 Git revision 复核，不重写旧证据，也不将旧名称解释为新运行结果。
+
+执行清单从 Python 的协议定义生成；不再提交重复 cases.json 或规划字段/组合表。
+`--catalog-only` 只检查可执行清单与上限引用，输出 VALID / NOT RUN，不冒充通过。
+`limits.json` 仍与 Rust 常量和边界断言校验。原始事件、命令/退出码、源/锁文件、
+对端身份、artifact hash、资源与清理证据独立复核；缺失/重复/部分结果不能 PASS。
+
+每轮新建 target/interop/runs 子目录；不得运行中修改源码。合成凭据/私有日志放临时
+目录并清理，不进入报告。Stop 时和后续静默窗口分别采样；短 tracer 不代替完整长测。
+容器不可用即 BLOCKED，不能退回宿主。完整规则见[测试隔离](../docs/testing-isolation.md)。
+
+### 对端下载
+
+```sh
+uv run --project scripts --locked vcore-scripts download mihomo
+uv run --project scripts --locked vcore-scripts download mihomo --target linux-arm64
+```
+
+使用官方 latest 下载链接；Mihomo 从 latest/download/version.txt 取得资产名所需版本，
+再通过二进制 -v 确认实际版本。不查 API、不固定旧版、不本地编译或静默复用旧缓存。
+同轮对端使用同一 release；下载/解压大小与超时有界，失败终止。产物在 target/interop，
+版本、URL、压缩包/二进制 SHA-256 和容器镜像 digest 随结果记录；本地摘要不是官方签名。
+
+所有协议端、原站、DNS、提供入口的对照客户端在本轮独占容器中；仅清理本轮所有者，
+不全局 stop/prune。默认 Mihomo，明确缺口由官方 Xray/V2Ray/Hysteria/ssserver 补验。
+唯一源码构建例外是获准的 xcaddy/Caddy H3/mTLS 网关，仍导入容器、不修改第三方。
+
+### 定向安全验证
+
+```sh
+uv run --project scripts --locked python -m vcore_scripts.protocol_fingerprint_shape target/interop/runs/
+uv run --project scripts --locked python -m vcore_scripts.protocol_fingerprint target/interop/runs/ --client-fingerprint chrome
+uv run --project scripts --locked python -m vcore_scripts.protocol_fingerprint_reference --list
+uv run --project scripts --locked python -m vcore_scripts.protocol_fingerprint_reference --run-dir target/interop/runs/
+uv run --project scripts --locked python -m vcore_scripts.protocol_fingerprint_reference --check-run target/interop/runs/
+uv run --project scripts --locked python -m vcore_scripts.protocol_jls target/interop/runs/
+uv run --project scripts --locked python -m vcore_scripts.protocol_encryption target/interop/runs/
+uv run --project scripts --locked vcore-scripts check reality-hybrid --run-dir target/interop/runs/
+```
+
+指纹验证的 reference、wire、interop 三层证据及 golden 比对规则见
+[指纹验证](../tests/fingerprints/README.md)。模板、主/下载身份、恢复/过期与容器数据面
+各有独立断言；不从别名、另一个模板或 fork 接口探针推导通过。更多参数读对应 --help。
+
+## 平台构建与产物
+
+```sh
uv run --project scripts --locked vcore-scripts build apple
uv run --project scripts --locked vcore-scripts build android
uv run --project scripts --locked vcore-scripts build windows
+# 正式候选要求干净、已提交的 checkout：
+uv run --project scripts --locked vcore-scripts build apple --delivery
+uv run --project scripts --locked vcore-scripts check platform-artifacts --manifest dist/apple/vcore-delivery.json
+uv run --project scripts --locked vcore-scripts check platform-abi --manifest dist/apple/vcore-delivery.json
```
-- Apple 命令只能在 macOS 运行，输出 `dist/apple/LibVCore.xcframework`。
-- Android 命令在 macOS/Linux 运行，默认输出 `dist/android/{arm64-v8a,x86_64}/libvcore.so`。
-- Windows 命令只能在已安装 Visual Studio C++ 工具的 Windows 运行；命令从系统注册表读取原生 ARM64/x64 处理器架构，通过 `vswhere` 加载对应的 MSVC 环境，验证三项 PE 的 machine type 后输出 `dist/windows/` 下的 DLL、Provider Host、Session Host 和记录 package integration revision、架构及三项 SHA-256 的 `vcore-windows-artifacts.json`。
-- 所有构建都使用 `Cargo.lock`，并检查产物内的 Invoke API v5/config revision 14 身份。
-- 标准 Apple、Android、Windows 构建显式包含两种客户端入站和四种出站，不依赖 `ffi` / `tun` 的传递 feature 来隐式补齐；不包含 `interop-test`。Apple/Android 的自定义 `VCORE_FEATURES` 不得将测试信任注入用于交付。
+- Apple 在 macOS 构建，输出 dist/apple/LibVCore.xcframework，包含 iOS、模拟器、macOS。
+ 最终链接 libc++；module map 已声明，直接 C 链接需 -lc++。
+- Android 在 macOS/Linux 构建，输出 dist/android 下两 ABI 的 libvcore.so 及配套
+ libc++_shared.so，宿主一起打包。NDK 优先 ANDROID_NDK_HOME，否则 ANDROID_HOME/ndk。
+- Windows 在原生 ARM64/x64、Visual Studio C++ 环境构建，输出配套 DLL/Provider Host/
+ Session Host 及架构/摘要。ARM64 需要 clang-cl/clang、Ninja；保持 BoringSSL 汇编启用。
+ 契约见 [Windows VPN](../docs/windows-vpn.md)。
-Apple/Android 继续接受现有环境变量：
+Apple/Android 可设置 VCORE_BUILD_PROFILE、VCORE_FEATURES、VCORE_APPLE_DIST_DIR、
+VCORE_IOS_DEPLOYMENT_TARGET、VCORE_MACOS_DEPLOYMENT_TARGET、VCORE_ANDROID_NDK_VERSION、
+VCORE_ANDROID_API、VCORE_ANDROID_TARGETS、VCORE_ANDROID_OUTPUT_DIR。默认值查看 builds.py；
+交付禁用隐藏覆盖、测试 feature、非 Release profile，标准 feature 集合显式包含所有支持协议。
-| 变量 | 默认值 |
-| --- | --- |
-| `VCORE_BUILD_PROFILE` | `release`，也可为 `debug` |
-| `VCORE_FEATURES` | `ffi,tun,inbound-http,inbound-socks5,outbound-anytls,outbound-socks5,outbound-shadowsocks,outbound-vless` |
-| `VCORE_APPLE_DIST_DIR` | `dist/apple` |
-| `VCORE_IOS_DEPLOYMENT_TARGET` | `13.0` |
-| `VCORE_MACOS_DEPLOYMENT_TARGET` | `10.15` |
-| `VCORE_ANDROID_NDK_VERSION` | `28.2.13676358` |
-| `VCORE_ANDROID_API` | `24` |
-| `VCORE_ANDROID_TARGETS` | `aarch64-linux-android x86_64-linux-android` |
-| `VCORE_ANDROID_OUTPUT_DIR` | `dist/android` |
+--delivery 绑定 commit/tree、lockfile、API/schema、features、toolchain/SDK/NDK、架构及
+全部文件大小/hash；所有平台在清旧记录或构建前拒绝输出路径及其仓库内祖先目录的
+符号链接和 Windows reparse point（包括 junction），不沿链接删除或写入外部产物。
+开始前清旧记录，失败不签收。Android 交付还会清空标准 dist/android
+构建输出，避免纳入开发构建遗留的额外 ABI。platform-artifacts 拒绝缺失/额外文件、
+错架构/身份及缺 C++ runtime；可重复 --manifest，--complete 要求 Apple、Android、
+原生 Windows ARM64/x64，仍只证明构建。--source-dir 须显式指定同一候选 checkout。
+platform-abi 在原生 macOS/Windows 链接/加载并执行 C ABI；Windows 另验 snapshot/
+未打包失败关闭，不创建业务运行时，不证明设备 VPN 或正式安装。
-Android NDK 优先读取 `ANDROID_NDK_HOME`，否则使用 `$ANDROID_HOME/ndk/`。
+## CI 与证据
-`.github/workflows/test.yml` 配置 macOS 的完整/精简协议 feature 检查，以及 Apple 五目标、Android 两 ABI、原生 Windows ARM64/x64 的 Release 构建和短期未签名产物归档。Android job 显式使用 NDK `28.2.13676358`，避免继承 runner 的另一默认版本；Linux runner 只作 Android 交叉构建，不意味着 VCore 支持 Linux 运行。runner 标签依据 [GitHub 官方清单](https://docs.github.com/en/actions/reference/runners/github-hosted-runners)。工作流配置不等于已执行的 CI 或设备验收，通过记录仍见 [验收矩阵](../docs/acceptance.md)。
+Tests 工作流只跑 core Debug/Release、quality/features 和 memory-only netstack；
+通用 Python、格式检查只在 quality 执行一次。Release builds 复用 Apple、Android、
+Windows ARM64/x64 构建，每个平台保留产物路径/架构/ABI 检查和未签名 artifacts。
+CI 配置存在不等于已运行或通过；原始 run URL、commit、artifact 有效期随当次记录。
-## 检查
-
-```bash
-uv run --project scripts --locked vcore-scripts check c-header
-uv run --project scripts --locked vcore-scripts check tls-dependencies
-uv run --project scripts --locked python -m unittest discover -s scripts/tests
-uv run --project scripts --locked ruff check scripts
-uv run --project scripts --locked ruff format --check scripts
-```
-
-`c-header` 在 macOS 使用 `xcrun clang/clang++`，其他平台使用 `PATH` 中的 `clang/clang++`。`tls-dependencies` 直接读取 `cargo metadata`，验证唯一的 OneVCore rustls 0.23.43 来自 GitHub `vcore/reality-0.23` 分支、官方 tokio-rustls 0.26.4、registry ring，并禁止 Watfaq 来源和 TLS 的 AWS-LC/FIPS provider。AWS-LC 仅允许出现在锁定官方 Shadowsocks 1.25.0 → registry shadowsocks-crypto 0.8.0 → aws-lc-rs → aws-lc-sys 链；额外使用方、非官方来源、重复版本和 FIPS 包均失败。该局部例外不更换 TLS/REALITY 的 ring provider。
-
-## Windows tun2socks demo
-
-后续协议互通统一使用下节的 mihomo harness。已有 Xray / anytls-go 脚本及本节的 Windows demo 保留为历史、显式专用入口，不作为新一轮协议互通的默认对端。
-
-```powershell
-uv run --project scripts --locked vcore-scripts demo windows-tun2socks
-uv run --project scripts --locked vcore-scripts demo windows-tun2socks C:\path\to\xray-config.json
-```
-
-该命令仍是显式互操作验收：它临时构建 `references/Xray-core`，使用已安装的 `VCore.UwpDemo.Dev` 示例 package，并在结束时停止测试 VPN 和删除临时文件。源配置不会被修改。真实配置、凭据和临时访问日志不得提交。
-
-## mihomo 协议互通
-
-使用独立 mihomo 进程验证公开 YAML → Invoke prepare/start → 实际数据路径。HTTP forward、分块上传、CONNECT 预读和 WebSocket Upgrade 各自验证以下两条路径，共 8 个场景：
-
-1. VCore HTTP 入站 → VCore SOCKS5 出站 → mihomo → 本机 origin。
-2. mihomo HTTP 入站 → mihomo HTTP 出站 → VCore CONNECT → 本机 origin。
-
-SOCKS5 另覆盖 CONNECT / UDP ASSOCIATE × IPv4 / IPv6 × 两个方向，共 8 个场景：VCore SOCKS5 入站 → VCore SOCKS5 出站 → mihomo，以及 mihomo SOCKS5 入站 → mihomo SOCKS5 出站 → VCore SOCKS5 入站。UDP 控制连接、端口学习与真实远端回包一并验证。
-
-AnyTLS 使用同一 mihomo 的独立 TLS listener：跳过常规验证、叶 pin、叶 pin + skip + 有序 ALPN 三种公开配置各覆盖 TCP/UoT × IPv4/IPv6 和独立 `measureDelay`，另检查默认不可信证书与错误 pin 的拒绝，共 17 项。证书由 PATH 中的 OpenSSL/LibreSSL 临时生成（RSA 2048，仅测试），因此需要可用的 `openssl` 命令；密钥和证书放在临时 mihomo dataDir，结束即清理。VCore 不开启测试信任注入或 `listeners` 配置。
-
-SS 使用三个独立 2022 listener 和合成 PSK，检查 TCP/UDP × IPv4/IPv6/域名及服务器先发，随后检查具体 SOCKS5 上游和嵌套组 / DIRECT 路径。域名仅使用 mihomo 测试 hosts 映射，不访问外网。SS 对端与首跳在不同进程，保留 mihomo 回环保护。
-
-该 mihomo 服务端不暴露 EIH 用户配置；`tests/mihomo/eih.rs` 的受控中继独立校验并剥离 AES 的 1/2 层身份头，业务密文仍交给 mihomo，明确区别于原生 EIH 服务端。错误身份/密钥/算法有 TCP/UDP 负例。另通过公开 Invoke 验证各算法的活动 TCP/UDP Stop、绑定失败回滚和独立测速，macOS 记录清理前后的 `/dev/fd` 数量；这些不替代完整压力与物理设备验收。
-
-```bash
-uv run --project scripts --locked vcore-scripts check mihomo-interop
-# 或传入现有独立对端二进制：
-bash tests/run_mihomo_interop.sh --binary /absolute/path/to/mihomo
-# 跨协议组合、Controller 切组、合成 utun 和重复生命周期：
-uv run --project scripts --locked vcore-scripts check mihomo-interop --extended
-# 30 分钟持续测试（单次通过不等于完整阶段签收，见下方限制）：
-uv run --project scripts --locked vcore-scripts check mihomo-interop --extended --soak-seconds 1800
-# macOS 推荐：上游和末端对端使用 Apple Container 独立 Linux VM：
-uv run --project scripts --locked vcore-scripts check mihomo-interop \
- --container-binary references/mihomo-linux-arm64 --extended --soak-seconds 1800
-```
-
-默认读取 `VCORE_MIHOMO_BIN` 或 `references/mihomo-test`。缺少二进制会明确失败并提示 NOT RUN，不进行下载或空跑。对已有参考 checkout，可自行构建：
-
-```bash
-git -C references/mihomo rev-parse HEAD
-go -C references/mihomo build -trimpath -o ../mihomo-test .
-```
-
-验收时记录源码完整 revision、Go 版本、构建 features 和 harness 输出的二进制版本 / SHA-256，不能只依赖自定义版本字符串。参考代码和二进制是独立研究对端，不加入 VCore 的生产依赖。
-
-默认模式四个对端仅开放本机回环，使用临时测试凭据、配置和 dataDir；origin 使用 IPv4/IPv6 回环，不启用系统 TUN，不改变系统代理或现有 mihomo 服务。容器模式的边界见下节。就绪期限 10 秒、socket I/O 与 Invoke 清理看门狗 5 秒、测试进程总期限 `300 + soak-seconds` 秒；退出或测试失败时停止并等待全部对端，必要时在 5 秒后强制结束，再移除本次临时目录。Invoke Stop 返回后检查 VCore TCP/UDP 端口可重绑。
-
-`--extended` 增加 VLESS/XHTTP stream-one/REALITY 对端，需要 OpenSSL 3 的 TLS 1.3/X25519 服务端能力；可用 `OPENSSL_BIN` 指定路径，或从常见 Homebrew 路径及 PATH 查找。伪装站点绑定回环（容器模式绑定专用 host-only bridge），证书和密钥由夹具生成，不启用测试信任注入。SOCKS5、AnyTLS、SS（AES-128 代表算法）、VLESS 的两跳 TCP/UDP 组合重复 8 轮，另检查真实 Controller 切组、HTTP-only 宿主生命周期、具体链 / DIRECT 测速快照与批量结果顺序，以及 100 次活动 Stop/失败回滚/独立测速。Apple 主机使用 UnixDatagram 对模拟 utun 帧入口，不创建系统接口，不能计为物理 TUN 验收。自建 mihomo 的带认证 Controller 只负责用例间清理自身连接，不接触已有服务。
-
-macOS 扩展入口另在同一 Running Session 中执行 100 次 32-flow 断连重建（120 秒看门狗），读取系统公开 `malloc_zone_statistics` 的在用堆字节数，并记录 RSS / FD 与 Stop 后状态。此采样不读取或输出分配内容、不改分配器；用于区分活对象增长和驻留内存现象，仍需人工审查趋势，不能仅凭进程退出成功判定没有泄漏。
-
-`--soak-seconds` 必须与 `--extended` 一起使用，范围 0–7200；非零时持续保持 16 TCP + 16 UDP flow，每秒切组、每分钟断开自建对端的连接并显式建立新客户端，逐包校验来源与负载，记录 RSS/FD/延迟。短于 1800 秒的运行只验证夹具，不能替代长测。当前资源采样仅在 macOS 主机执行；测试内含节流，输出的负载速率不是最大吞吐基准。
-
-测试隔离：入口使用跨进程非阻塞锁，另一套 harness 在启动服务前失败；Python 同时预留回环 TCP/UDP 的 IPv4、IPv6 端口，IPv4-only 对端启动后保留 IPv6 guard。Rust 测试客户端、origin 和 EIH 中继也持有另一地址族的 UDP guard，直到对应 socket 释放。所有 IPv6 guard 为 v6-only，不启用地址复用，不关闭 IPv6 测试；仅在流量启动前有界重选占用端口，不重试业务包。32 个活动 flow 的进程 FD 比原夹具增加 32，来自 UDP 客户端/origin 的测试 guard，结束后仍必须回到空闲基线。第三方源码及 VCore 生产 socket 创建策略不因该隔离改动而改变。
-
-历史失败与当前门槛：2026-09-17 的首次 1800 秒长测约 8 分半后出现 UDP 来源异常。该 macOS 环境独立复现了 IPv6 双栈 UDP 自动端口与 IPv4 socket 同号、回包进入无关 IPv4 socket 的现象；并行短测也出现 UDP 超时，但未保留完整 socket 映射，不能把两次失败都断言为已逐跳证明的同一原因。端口隔离后一次完整 30 分钟通过，FD 回到 6；随后加入的 100 次快速重建检查两次 FAIL，第二次在第 11 轮同时捕获 mihomo 的回环拒绝日志和自建进程 UDP 映射：AnyTLS 的来源端口与同一 mihomo 的另一个 UDP 出口端口同号，触发按来源端口匹配的保护。保护测试端点不能约束所有内部自动端口，清理用例间连接也不能排除同轮活动流之间的同号端口。首次快速重建的回包超时未获得同等根因证据，单独保留。
-
-UDP 失败时，macOS 夹具在退出前用有界 `lsof` 采样，仅检查本测试进程和 Python 入口提供的自建本机对端 PID，不读取负载、不检查无关进程；容器进程不伪装成 macOS PID，失败时另读取本次容器日志。来源校验、mihomo 回环保护及所有原始失败记录保留，不重试业务包来规避失败。
-
-默认 Cargo 测试会将外部互通标记 ignored，必须显式执行 harness 才算有外部对端证据。2026-09-17 的 Apple Container 组合/资源验收结果见下节及 [验收矩阵](../docs/acceptance.md)；VLESS 的其他模式、设备和安装包结果不能从当前夹具推导，也不把旧对端或同库回环结果改写为 mihomo 结果。
-
-### Apple Container 对端
-
-需要已安装并运行的 Apple `container`（当前实际使用 1.4.1，macOS 27 / arm64）。先准备一次专用 host-only 网络、固定摘要的基础镜像及未修改的 mihomo Linux ARM64 程序；若同名网络已存在，先检查其 `mode=hostOnly` 和 `purpose=vcore-mihomo-interop` 标签，不覆盖其他网络：
-
-```bash
-container network inspect vcore-mihomo-interop
-# 仅在该网络不存在时创建：
-container network create --internal --label purpose=vcore-mihomo-interop vcore-mihomo-interop
-container image pull --arch arm64 docker.io/library/alpine@sha256:fd791d74b68913cbb027c6546007b3f0d3bc45125f797758156952bc2d6daf40
-git -C references/mihomo rev-parse HEAD
-CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go -C references/mihomo build -trimpath \
- -ldflags '-X github.com/metacubex/mihomo/constant.Version=vcore-interop-ab405bad' \
- -o ../mihomo-linux-arm64 .
-```
-
-本次源码完整 revision 为 `ab405bad5beeeac8b003bb01f60f134f6df54471`，Go 1.27.1、未添加 build tags，Linux 程序 SHA-256 为 `eb35562be501dd6cd9e1f8bdf3ba43162bf6abb6a3946cd1f1ec0511462feab2`。`--binary` / `VCORE_MIHOMO_BIN` 仍指定原生 macOS 程序，`--container-binary` 单独指定 Linux 程序。缺少基础镜像、网络或二进制会失败，不降级到本机、不自行拉取不同版本。
-
-- 首跳与末跳分别在两个 Linux VM 中，每个 1 CPU / 256 MiB；只读根和夹具挂载，临时可写 dataDir。直接访问隔离网络 IP，不发布宿主端口，不配置系统 DNS/PF、代理或 TUN，不关闭 mihomo 回环保护。
-- origin 和 REALITY 伪装站点只绑定该 host-only bridge 的地址，保留 IPv4 / IPv6 数据校验；启动时发现实际地址，不硬编码 DHCP 或 SLAAC 地址。排除尚处于 DAD、重复或失效状态的 IPv6 地址，再验证可绑定及两个容器可达，全部发生在业务测试前。域名 origin 和末端节点分别映射，避免把容器回环当成宿主。
-- 反向 HTTP/SOCKS5 入站测试仍使用两个原生 mihomo 进程，VCore 保持仅回环监听和原有认证。这不是四个对端全容器化，也不是 LAN 共享或物理 IPv6 验收。
-- 每次分配唯一容器名；成功、断言失败、超时或启动失败均只清理本次已创建且带标签的容器及临时目录。保留专用网络、缓存镜像和研究二进制供下次使用，不执行全局 stop/prune。
-
-网络行为依据 [Apple Container 1.4.1 networking](https://github.com/apple/container/blob/1.4.1/docs/networking.md)。虚拟网络通过只证明该受控环境，不等于已经修复 macOS 同内核碰撞或第三方实现。
-
-本次完整入口通过全部基础/扩展检查、100 次快速 32-flow 重建和 1800 秒长测：1,734 次切组、29 次断连重建、420,476,672 字节校验，FD 为 6 → 195 → 6。RSS 活动起始 / 峰值 / 结束 / Stop 后为 19,248 / 21,984 / 19,184 / 18,896 KiB；多次 `heap --noContent` 采样的存活分配约 2,109–2,127 个、4.90–4.91 MB，未随 RSS 同步累积。堆诊断会扰动延迟（最大 wave 441 ms），节流负载速率不是吞吐基准；32-flow 初次 / 末次建连为 204 / 153 ms。容器、原生对端与临时配置清理完成，专用网络及镜像缓存保留。最初适配中的固定回环断言、IPv6 地址未就绪，以及此前所有本机失败均保留，不用最终通过覆盖历史。
+真实设备、正式宿主、签名安装和商店发布单独签收，见[验收边界](../docs/acceptance.md)。
+旧 Windows tun2socks demo 是显式平台人工验收工具，不是允许在宿主运行协议服务端的例外。
diff --git a/scripts/cmake/android.toolchain.cmake b/scripts/cmake/android.toolchain.cmake
new file mode 100644
index 0000000..af9ca86
--- /dev/null
+++ b/scripts/cmake/android.toolchain.cmake
@@ -0,0 +1,7 @@
+# Let the NDK select C/C++/ASM compilers consistently across repeated configure
+# calls. Passing a target clang wrapper as CMAKE_C_COMPILER makes the NDK replace
+# it, which triggers CMake's cache reset on boring-sys's second configure.
+set(ANDROID_ABI "$ENV{VCORE_CMAKE_ANDROID_ABI}")
+set(ANDROID_PLATFORM "android-$ENV{VCORE_CMAKE_ANDROID_API}")
+set(ANDROID_STL c++_shared)
+include("$ENV{ANDROID_NDK_HOME}/build/cmake/android.toolchain.cmake")
diff --git a/scripts/cmake/windows-arm64.toolchain.cmake b/scripts/cmake/windows-arm64.toolchain.cmake
new file mode 100644
index 0000000..14a748c
--- /dev/null
+++ b/scripts/cmake/windows-arm64.toolchain.cmake
@@ -0,0 +1,14 @@
+# Native Windows ARM64, MSVC ABI. Clang's integrated assembler handles BoringSSL
+# preprocessed .S files; Ninja preserves their directory-qualified object names.
+# Never disable assembly or change the bundled third-party source.
+set(CMAKE_SYSTEM_NAME Windows)
+set(CMAKE_SYSTEM_PROCESSOR ARM64)
+set(CMAKE_C_COMPILER "$ENV{CC_aarch64_pc_windows_msvc}")
+set(CMAKE_CXX_COMPILER "$ENV{CXX_aarch64_pc_windows_msvc}")
+# cmake-rs supplies MSVC-style ASM flags as well as C/C++ flags. Use the CL
+# driver for all three languages so the integrated assembler accepts them.
+set(CMAKE_ASM_COMPILER "$ENV{CC_aarch64_pc_windows_msvc}")
+set(CMAKE_C_COMPILER_TARGET aarch64-pc-windows-msvc)
+set(CMAKE_CXX_COMPILER_TARGET aarch64-pc-windows-msvc)
+set(CMAKE_ASM_COMPILER_TARGET aarch64-pc-windows-msvc)
+set(CMAKE_MSVC_RUNTIME_LIBRARY MultiThreaded)
diff --git a/scripts/fixtures/platform_abi.c b/scripts/fixtures/platform_abi.c
new file mode 100644
index 0000000..e2c05b8
--- /dev/null
+++ b/scripts/fixtures/platform_abi.c
@@ -0,0 +1,47 @@
+/* Production artifact consumer. No runtime instance, sockets, or test features. */
+#include
+#include
+#include "vcore.h"
+#ifdef _WIN32
+#include
+#endif
+
+int main(int argc, char **argv) {
+#ifdef _WIN32
+ if (argc != 2) return 10;
+ HMODULE library = LoadLibraryExA(argv[1], NULL,
+ LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR | LOAD_LIBRARY_SEARCH_DEFAULT_DIRS);
+ if (!library) return 11;
+ /* memcpy avoids a nonportable data-pointer/function-pointer cast. */
+ FARPROC invoke_address = GetProcAddress(library, "VCoreInvoke");
+ FARPROC free_address = GetProcAddress(library, "VCoreFree");
+ char *(*invoke)(const char *) = NULL;
+ void (*release)(char *) = NULL;
+ if (!invoke_address || !free_address) return 12;
+ memcpy(&invoke, &invoke_address, sizeof(invoke));
+ memcpy(&release, &free_address, sizeof(release));
+#else
+ (void)argc;
+ (void)argv;
+ char *(*invoke)(const char *) = VCoreInvoke;
+ void (*release)(char *) = VCoreFree;
+#endif
+ for (unsigned i = 0; i < 1000; i++) {
+ char *response = invoke("{\"apiVersion\":5,\"method\":\"version\",\"payload\":{}}");
+ int valid = response && strstr(response, "\"success\":true")
+ && strstr(response, "\"apiVersion\":5")
+ && strstr(response, "\"configVersion\":27")
+ && strstr(response, "VCore;engine=rust;coreVersion=0.1.0;invokeApiVersion=5;configVersion=27");
+ release(response);
+ if (!valid) return 20;
+ }
+ char *invalid = invoke("{\"apiVersion\":4,\"method\":\"version\",\"payload\":{}}");
+ int rejected = invalid && strstr(invalid, "\"success\":false");
+ release(invalid);
+ if (!rejected) return 21;
+ puts("PASS production ABI: 1000 version/free calls; incompatible API rejected");
+#ifdef _WIN32
+ FreeLibrary(library);
+#endif
+ return 0;
+}
diff --git a/scripts/src/vcore_scripts/builds.py b/scripts/src/vcore_scripts/builds.py
index c0e3615..b75c758 100644
--- a/scripts/src/vcore_scripts/builds.py
+++ b/scripts/src/vcore_scripts/builds.py
@@ -13,11 +13,12 @@ from pathlib import Path
CORE_DIR = Path(__file__).resolve().parents[3]
EXPECTED_IDENTITY = (
- b"VCore;engine=rust;coreVersion=0.1.0;invokeApiVersion=5;configVersion=14"
+ b"VCore;engine=rust;coreVersion=0.1.0;invokeApiVersion=5;configVersion=27"
)
DEFAULT_FEATURES = (
"ffi,tun,inbound-http,inbound-socks5,outbound-anytls,"
- "outbound-socks5,outbound-shadowsocks,outbound-vless"
+ "outbound-socks5,outbound-shadowsocks,outbound-trojan,outbound-vmess,outbound-vless,"
+ "outbound-hysteria2"
)
@@ -196,17 +197,34 @@ def build_android() -> None:
for target in targets:
abi, clang, cargo_name = _android_target(target, android_api)
linker = toolchain / "bin" / clang
+ cpp = toolchain / "bin" / (clang + "++")
archive = toolchain / "bin" / "llvm-ar"
if not linker.is_file():
raise RuntimeError(f"Android linker not found: {linker}")
if not archive.is_file():
raise RuntimeError(f"Android archiver not found: {archive}")
+ if not cpp.is_file():
+ raise RuntimeError(f"Android C++ compiler not found: {cpp}")
+ runtime_target = (
+ "arm-linux-androideabi" if target == "armv7-linux-androideabi" else target
+ )
+ cpp_runtime = (
+ toolchain / "sysroot/usr/lib" / runtime_target / "libc++_shared.so"
+ )
+ if not cpp_runtime.is_file():
+ raise RuntimeError(f"Android C++ runtime not found: {cpp_runtime}")
target_env = target.replace("-", "_")
env = base_env | {
f"CC_{target_env}": str(linker),
+ f"CXX_{target_env}": str(cpp),
f"AR_{target_env}": str(archive),
f"CARGO_TARGET_{cargo_name}_LINKER": str(linker),
f"CARGO_TARGET_{cargo_name}_AR": str(archive),
+ f"CMAKE_TOOLCHAIN_FILE_{target_env}": str(
+ CORE_DIR / "scripts/cmake/android.toolchain.cmake"
+ ),
+ "VCORE_CMAKE_ANDROID_ABI": abi,
+ "VCORE_CMAKE_ANDROID_API": android_api,
}
_cargo_build(target, profile_flags, features, env)
artifact = CORE_DIR / "target" / target / profile_name / "libvcore.so"
@@ -214,6 +232,9 @@ def build_android() -> None:
destination = output / abi / "libvcore.so"
destination.parent.mkdir(parents=True, exist_ok=True)
shutil.copy2(artifact, destination)
+ # BoringSSL links the NDK shared C++ runtime. It is not supplied by
+ # Android itself; distribute the matching ABI/runtime alongside VCore.
+ shutil.copy2(cpp_runtime, destination.parent / cpp_runtime.name)
print(output)
@@ -368,6 +389,30 @@ def _windows_msvc_environment(architecture: str) -> dict[str, str]:
key, separator, value = line.partition("=")
if separator and key:
env[key] = value
+ if architecture == "arm64":
+ search_path = next(value for key, value in env.items() if key.upper() == "PATH")
+ compilers = {
+ name: shutil.which(name, path=search_path)
+ for name in ("clang-cl", "clang", "ninja")
+ }
+ if not all(compilers.values()):
+ raise RuntimeError(
+ "native Windows ARM64 requires LLVM clang-cl/clang and Ninja"
+ )
+ # Visual Studio's generator does not assemble BoringSSL's preprocessed
+ # .S inputs. Keep assembly enabled using LLVM + Ninja, still MSVC ABI,
+ # the selected Windows SDK, and the same static CRT. No source patch.
+ env.update(
+ {
+ "CC_aarch64_pc_windows_msvc": compilers["clang-cl"],
+ "CXX_aarch64_pc_windows_msvc": compilers["clang-cl"],
+ "VCORE_WINDOWS_ARM64_CLANG": compilers["clang"],
+ "CMAKE_GENERATOR_aarch64_pc_windows_msvc": "Ninja",
+ "CMAKE_TOOLCHAIN_FILE_aarch64_pc_windows_msvc": str(
+ CORE_DIR / "scripts/cmake/windows-arm64.toolchain.cmake"
+ ),
+ }
+ )
return env
diff --git a/scripts/src/vcore_scripts/caddy_build.py b/scripts/src/vcore_scripts/caddy_build.py
new file mode 100644
index 0000000..48580d6
--- /dev/null
+++ b/scripts/src/vcore_scripts/caddy_build.py
@@ -0,0 +1,128 @@
+"""Explicit xcaddy-only exception for the isolated H3/mTLS test gateway."""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+from .native_release import PeerArtifact
+from .protocol_inputs import redact, sha256
+from .protocol_peers import run_command
+
+
+def latest_tag(project):
+ """Official latest redirect, not the GitHub API or a pinned old tag."""
+ if project not in ("caddy", "xcaddy"):
+ raise ValueError("unsupported gateway project")
+ url = f"https://github.com/caddyserver/{project}/releases/latest"
+ request = urllib.request.Request(
+ url, method="HEAD", headers={"User-Agent": "VCore-interop-scripts"}
+ )
+ with urllib.request.urlopen(request, timeout=30) as response:
+ final = urllib.parse.urlsplit(response.geturl())
+ prefix = f"/caddyserver/{project}/releases/tag/"
+ tag = final.path.removeprefix(prefix)
+ if (
+ final.scheme != "https"
+ or final.netloc != "github.com"
+ or final.query
+ or final.fragment
+ or not final.path.startswith(prefix)
+ or not re.fullmatch(r"v[0-9]+\.[0-9]+\.[0-9]+", tag)
+ ):
+ raise RuntimeError("cannot resolve official stable gateway release")
+ return tag
+
+
+def build_caddy(directory: Path):
+ directory.mkdir(parents=True, exist_ok=False)
+ xcaddy, go = shutil.which("xcaddy"), shutil.which("go")
+ if not xcaddy or not go:
+ raise RuntimeError("xcaddy and Go are required for the approved gateway build")
+ versions = {project: latest_tag(project) for project in ("xcaddy", "caddy")}
+ tool = run_command([xcaddy, "version"], timeout=10, limit=4096)
+ if (
+ tool.returncode
+ or not tool.cleanup
+ or tool.stdout.decode().split()[0] != versions["xcaddy"]
+ ):
+ raise RuntimeError(
+ "installed xcaddy must match the official latest stable release"
+ )
+ compiler = run_command([go, "version"], timeout=10, limit=4096)
+ if compiler.returncode or not compiler.cleanup:
+ raise RuntimeError("cannot read Go build identity")
+ temporary = directory / "build-work"
+ temporary.mkdir()
+ binary = directory / "caddy"
+ environment = os.environ.copy()
+ # A fresh standard-module build, never a local source replacement or plugin.
+ for key in tuple(environment):
+ if key.startswith("XCADDY_") or key in ("CADDY_VERSION", "GOFLAGS", "GOWORK"):
+ environment.pop(key)
+ environment.update(
+ GOOS="linux",
+ GOARCH="arm64",
+ CGO_ENABLED="0",
+ GOWORK="off",
+ XCADDY_SKIP_CLEANUP="1",
+ XCADDY_PRINT_VERSION="0",
+ TMPDIR=str(temporary),
+ )
+ print("Building official latest Caddy with xcaddy for linux/arm64", flush=True)
+ built = run_command(
+ [xcaddy, "build", "latest", "--output", str(binary)],
+ env=environment,
+ cwd=directory,
+ timeout=600,
+ limit=4 * 1024 * 1024,
+ )
+ (directory / "build.log").write_text(redact(built.stdout.decode(errors="replace")))
+ if built.returncode or not built.cleanup or not binary.is_file():
+ raise RuntimeError("xcaddy gateway build failed")
+ metadata = run_command([go, "version", "-m", str(binary)], timeout=10, limit=65536)
+ info = metadata.stdout.decode(errors="replace")
+ expected = f"\tdep\tgithub.com/caddyserver/caddy/v2\t{versions['caddy']}\t"
+ if (
+ metadata.returncode
+ or not metadata.cleanup
+ or expected not in info
+ or "=>" in info
+ ):
+ raise RuntimeError("gateway build is not the unmodified official latest Caddy")
+ # xcaddy deliberately uses cwd on macOS, TMPDIR on other hosts.
+ manifests = [
+ *directory.glob("buildenv_*/go.mod"),
+ *temporary.glob("buildenv_*/go.mod"),
+ ]
+ if len(manifests) != 1:
+ raise RuntimeError("xcaddy build manifest is missing or ambiguous")
+ inputs = {}
+ for name in ("go.mod", "go.sum", "main.go"):
+ source = manifests[0].with_name(name)
+ shutil.copyfile(source, directory / name)
+ inputs[name] = sha256(source)
+ # Omit the host executable path from the retained module metadata.
+ (directory / "modules.txt").write_text("\n".join(info.splitlines()[1:]) + "\n")
+ return PeerArtifact(
+ binary,
+ dict(
+ kind="Caddy-xcaddy",
+ target="linux-arm64",
+ source_built=True,
+ source_url="https://github.com/caddyserver/caddy/releases/latest",
+ release=versions["caddy"],
+ xcaddy_version=tool.stdout.decode().strip(),
+ go_version=compiler.stdout.decode().strip(),
+ binary_sha256=sha256(binary),
+ build_seconds=built.seconds,
+ build_cleanup=built.cleanup,
+ inputs=inputs,
+ extra_plugins=[],
+ version=None,
+ ),
+ )
diff --git a/scripts/src/vcore_scripts/checks.py b/scripts/src/vcore_scripts/checks.py
index 9122251..fc451c6 100644
--- a/scripts/src/vcore_scripts/checks.py
+++ b/scripts/src/vcore_scripts/checks.py
@@ -13,13 +13,9 @@ CRATES_IO_SOURCES = {
"registry+https://github.com/rust-lang/crates.io-index",
"registry+https://index.crates.io/",
}
-RUSTLS_GIT_SOURCE_PREFIX = (
- "git+https://github.com/OneVCore/rustls?branch=vcore/reality-0.23#"
-)
-SHADOWSOCKS_REVISION = "ab388c7466d21f979430e33cc9ef10e22fb05955"
-SHADOWSOCKS_GIT_SOURCE = (
- "git+https://github.com/shadowsocks/shadowsocks-rust.git"
- f"?rev={SHADOWSOCKS_REVISION}#{SHADOWSOCKS_REVISION}"
+BORING_REVISION = "d5a5d41850886aef5b269015130ee6d6eb2129ba"
+BORING_GIT_SOURCE = (
+ f"git+https://github.com/OneXray/boring?branch=release#{BORING_REVISION}"
)
_C_SOURCE = r"""#include "vcore.h"
@@ -100,7 +96,7 @@ def _shadowsocks_aws_lc_errors(metadata: dict[str, Any]) -> list[str]:
errors: list[str] = []
allowed: dict[str, dict[str, Any]] = {}
expected = {
- "shadowsocks": ("1.25.0", {SHADOWSOCKS_GIT_SOURCE}),
+ "shadowsocks": ("1.25.0", CRATES_IO_SOURCES),
"shadowsocks-crypto": ("0.8.0", CRATES_IO_SOURCES),
"aws-lc-rs": (None, CRATES_IO_SOURCES),
"aws-lc-sys": (None, CRATES_IO_SOURCES),
@@ -178,8 +174,8 @@ def _tls_dependency_errors(metadata: dict[str, Any]) -> list[str]:
return None
return matches[0]
- rustls = require_single("rustls", "0.23.43")
- tokio_rustls = require_single("tokio-rustls", "0.26.4")
+ rustls = require_single("rustls", "0.23.45")
+ tokio_rustls = require_single("tokio-rustls", "0.26.5")
ring = named("ring")
if len(ring) != 1:
@@ -195,12 +191,9 @@ def _tls_dependency_errors(metadata: dict[str, Any]) -> list[str]:
if rustls is not None:
rustls_source = rustls.get("source") or ""
- revision = rustls_source.removeprefix(RUSTLS_GIT_SOURCE_PREFIX)
- if len(revision) != 40 or any(
- character not in "0123456789abcdef" for character in revision
- ):
+ if rustls_source not in CRATES_IO_SOURCES:
errors.append(
- "rustls must come from the vcore/reality-0.23 GitHub branch; "
+ "rustls must come from crates.io; "
f"resolved source: {rustls_source or 'path'}"
)
@@ -226,8 +219,8 @@ def _tls_dependency_errors(metadata: dict[str, Any]) -> list[str]:
errors.append("rustls is missing from the resolved dependency graph")
else:
features = set(rustls_node["features"])
- missing = {"reality", "ring"} - features
- forbidden = {"aws_lc_rs", "fips"} & features
+ missing = {"ring"} - features
+ forbidden = {"reality", "aws_lc_rs", "fips"} & features
if missing:
errors.append(
f"rustls is missing required features: {', '.join(sorted(missing))}"
@@ -238,6 +231,63 @@ def _tls_dependency_errors(metadata: dict[str, Any]) -> list[str]:
f"{', '.join(sorted(forbidden))}"
)
+ native = {}
+ node_by_id = {node["id"]: node for node in nodes}
+ hpke = require_single("hpke", "0.14.1")
+ if hpke is not None:
+ if hpke.get("source") not in CRATES_IO_SOURCES:
+ errors.append("hpke must be the unmodified crates.io release")
+ hpke_node = node_by_id.get(hpke["id"])
+ if hpke_node is None or set(hpke_node.get("features", [])) != {
+ "alloc",
+ "aes",
+ "chacha",
+ "x25519",
+ "hkdfsha2",
+ }:
+ errors.append("hpke must use only the approved ECH algorithms")
+ for name, required in (
+ ("boring", {"reality", "client-fingerprint", "shadow-tls-v3", "jls"}),
+ ("boring-sys", {"reality", "shadow-tls-v3", "jls"}),
+ ("tokio-boring", set()),
+ ):
+ package = require_single(name, "5.2.0")
+ if package is None:
+ continue
+ native[name] = package
+ if package.get("source") != BORING_GIT_SOURCE:
+ errors.append(
+ f"{name} must use the approved boring release branch "
+ "and locked revision"
+ )
+ node = node_by_id.get(package["id"])
+ if node is None:
+ errors.append(f"{name} is missing from the resolved graph")
+ continue
+ features = set(node["features"])
+ if not required <= features:
+ errors.append(f"{name} is missing required TLS features")
+ if features & {
+ "fips",
+ "fips-precompiled",
+ "rpk",
+ "pq-experimental",
+ "restls",
+ }:
+ errors.append(f"{name} enables an unapproved native TLS mode")
+ for parent, children in (
+ ("boring", {"boring-sys"}),
+ ("tokio-boring", {"boring", "boring-sys"}),
+ ):
+ if parent in native:
+ deps = {
+ dep["pkg"]
+ for dep in node_by_id.get(native[parent]["id"], {}).get("deps", [])
+ }
+ for child in children:
+ if child not in native or native[child]["id"] not in deps:
+ errors.append(f"{parent} must directly use the locked {child}")
+
errors.extend(_shadowsocks_aws_lc_errors(metadata))
return errors
@@ -273,12 +323,19 @@ def check_tls_dependencies() -> None:
rustls = next(
package for package in metadata["packages"] if package["name"] == "rustls"
)
- revision = rustls["source"].rsplit("#", 1)[1]
print("TLS dependency check passed:")
- print(f"- one OneVCore rustls 0.23.43 vcore/reality-0.23 @ {revision[:12]}")
- print("- one official tokio-rustls 0.26.4")
+ print(f"- one official crates.io rustls {rustls['version']}")
+ print("- one official tokio-rustls 0.26.5")
+ print("- one official hpke 0.14.1 with the approved static ECH algorithms")
+ print(
+ "- one boring/boring-sys/tokio-boring 5.2.0 release branch "
+ f"@ {BORING_REVISION[:12]}"
+ )
print(f"- one registry ring {ring['version']} provider")
- print("- no Watfaq or second rustls version; TLS uses ring only")
+ print(
+ "- unprofiled TLS/QUIC use rustls + ring; REALITY/named profiles use BoringSSL"
+ )
+ print("- no Watfaq, second rustls source or rustls REALITY backend")
if any(p["name"] == "aws-lc-rs" for p in metadata["packages"]):
print("- AWS-LC is restricted to the pinned official Shadowsocks 2022 chain")
else:
diff --git a/scripts/src/vcore_scripts/cli.py b/scripts/src/vcore_scripts/cli.py
index a9dfa75..e1f0deb 100644
--- a/scripts/src/vcore_scripts/cli.py
+++ b/scripts/src/vcore_scripts/cli.py
@@ -8,7 +8,10 @@ from pathlib import Path
from .builds import build_android, build_apple, build_windows
from .checks import check_c_header, check_tls_dependencies
-from .mihomo import run_mihomo_interop
+from .mihomo_release import SUPPORTED_TARGETS, download_mihomo
+from .protocol_catalogs import CATALOG_DIR, SUITES, check_protocol_catalogs
+from .protocol_evidence import check_run
+from .protocol_harness import run_protocol_interop
from .tun2socks import run_demo
@@ -21,41 +24,124 @@ def _parser() -> argparse.ArgumentParser:
build = commands.add_parser("build", help="build platform artifacts")
platforms = build.add_subparsers(dest="platform", required=True)
- platforms.add_parser("apple", help="build LibVCore.xcframework on macOS")
- platforms.add_parser("android", help="build Android libvcore.so artifacts")
- platforms.add_parser("windows", help="build packaged Windows artifacts")
+ for name, description in (
+ ("apple", "build LibVCore.xcframework on macOS"),
+ ("android", "build Android libvcore.so artifacts"),
+ ("windows", "build packaged Windows artifacts"),
+ ):
+ command = platforms.add_parser(name, help=description)
+ command.add_argument(
+ "--delivery",
+ action="store_true",
+ help="record production artifact identity",
+ )
+
+ download = commands.add_parser("download", help="download official test peers")
+ downloads = download.add_subparsers(dest="download", required=True)
+ peer = downloads.add_parser("mihomo", help="download the latest stable mihomo")
+ peer.add_argument(
+ "--target", choices=SUPPORTED_TARGETS, help="default: host platform"
+ )
check = commands.add_parser("check", help="run repository checks")
checks = check.add_subparsers(dest="check", required=True)
+ core = checks.add_parser(
+ "core", help="run memory-only tests or feature/build checks"
+ )
+ core.add_argument(
+ "--profile", choices=("debug", "release", "features"), default="debug"
+ )
+ core.add_argument("--list", dest="list_only", action="store_true")
checks.add_parser("c-header", help="compile vcore.h as C and C++")
checks.add_parser("tls-dependencies", help="validate the locked TLS graph")
- mihomo = checks.add_parser(
- "mihomo-interop", help="run local protocol interoperability against mihomo"
+ delivery = checks.add_parser(
+ "platform-artifacts", help="verify production artifact evidence, not devices"
)
- mihomo.add_argument("--binary", type=Path)
- mihomo.add_argument(
- "--container-binary",
- type=Path,
- help="run upstream/terminal peers in Apple Container (Linux ARM64 binary)",
- )
- mihomo.add_argument(
- "--extended",
+ delivery.add_argument("--manifest", type=Path, action="append", required=True)
+ delivery.add_argument("--source-dir", type=Path)
+ delivery.add_argument(
+ "--complete",
action="store_true",
- help="include repeated cross-protocol two-hop gates",
+ help="require every production platform group",
)
- mihomo.add_argument(
- "--soak-seconds",
- type=int,
- default=0,
- help="requires --extended; full soak acceptance needs 1800 wall-clock seconds",
+ abi = checks.add_parser("platform-abi", help="link/load native production artifact")
+ abi.add_argument("--manifest", type=Path, required=True)
+ reality = checks.add_parser(
+ "reality-hybrid",
+ help="verify isolated hybrid REALITY, not the complete security suite",
+ )
+ reality.add_argument("--run-dir", type=Path, required=True)
+ reality.add_argument("--case", dest="identifiers", action="append")
+ xhttp = checks.add_parser(
+ "xhttp-peers",
+ help="probe isolated native XHTTP peer capabilities, not suite acceptance",
+ )
+ xhttp.add_argument("--run-dir", type=Path, required=True)
+ xhttp.add_argument(
+ "--identities-only",
+ action="store_true",
+ help="probe real download-leg client-identity enforcement only",
+ )
+ gateway = checks.add_parser(
+ "xhttp-gateway",
+ help="build xcaddy and test isolated H3/mTLS native topology",
+ )
+ gateway.add_argument("--run-dir", type=Path, required=True)
+ gateway.add_argument(
+ "--identities-only",
+ action="store_true",
+ help="small identity probes with native QUIC certificate-error observation",
+ )
+ coverage = checks.add_parser(
+ "protocol-coverage", help="validate executable catalogs or persisted evidence"
+ )
+ coverage_modes = coverage.add_mutually_exclusive_group(required=True)
+ coverage_modes.add_argument(
+ "--catalog-only",
+ action="store_true",
+ help="check declarations only, not implementation or behavior acceptance",
+ )
+ coverage_modes.add_argument(
+ "--run-dir", type=Path, help="validate a complete persisted suite run"
+ )
+ suites = [name.lower() for name in SUITES]
+ coverage.add_argument("--suite", choices=suites, default="foundations")
+ coverage.add_argument(
+ "--manifest",
+ type=Path,
+ help="explicit frozen executable manifest for evidence checks",
+ )
+ protocol = checks.add_parser(
+ "protocol-interop", help="run a protocol or integration capability suite"
+ )
+ protocol.add_argument(
+ "--suite", choices=suites, required=True, help="capability suite to run"
+ )
+ protocol.add_argument("--case", dest="identifiers", action="append")
+ protocol.add_argument(
+ "--protocol",
+ choices=[
+ "foundation",
+ "legacy",
+ "trojan",
+ "vmess",
+ "vless",
+ "hysteria2",
+ ],
+ )
+ modes = protocol.add_mutually_exclusive_group()
+ modes.add_argument("--list", dest="list_only", action="store_true")
+ modes.add_argument("--preflight", dest="preflight_only", action="store_true")
+ protocol.add_argument(
+ "--run-dir", type=Path, help="fresh child directory of target/interop/runs"
)
-
demo = commands.add_parser("demo", help="run opt-in interoperability demos")
demos = demo.add_subparsers(dest="demo", required=True)
tun2socks = demos.add_parser(
"windows-tun2socks", help="run VCore TUN through an external Xray SOCKS inbound"
)
- tun2socks.add_argument("config", nargs="?", type=Path)
+ tun2socks.add_argument("config", type=Path)
+ tun2socks.add_argument("--xray-source", type=Path, required=True)
return parser
@@ -63,29 +149,69 @@ def main(argv: Sequence[str] | None = None) -> int:
args = _parser().parse_args(argv)
try:
if args.command == "build":
- if args.platform == "apple":
+ if args.delivery:
+ from .platform_delivery import build_delivery
+
+ build_delivery(args.platform)
+ elif args.platform == "apple":
build_apple()
elif args.platform == "android":
build_android()
else:
build_windows()
+ elif args.command == "download":
+ download_mihomo(args.target)
elif args.command == "check":
- if args.check == "c-header":
+ if args.check == "core":
+ from .core_checks import run
+
+ run(args.profile, list_only=args.list_only)
+ elif args.check == "c-header":
check_c_header()
- elif args.check == "mihomo-interop":
- if args.extended or args.soak_seconds or args.container_binary:
- run_mihomo_interop(
- args.binary,
- extended=args.extended,
- soak_seconds=args.soak_seconds,
- container_binary=args.container_binary,
- )
+ elif args.check == "platform-artifacts":
+ from .platform_delivery import check_delivery
+
+ check_delivery(
+ args.manifest, source_dir=args.source_dir, complete=args.complete
+ )
+ elif args.check == "platform-abi":
+ from .platform_delivery import check_abi
+
+ check_abi(args.manifest.resolve())
+ elif args.check == "xhttp-peers":
+ from .protocol_xhttp_peers import main as xhttp_peers
+
+ return xhttp_peers(args.run_dir, identities_only=args.identities_only)
+ elif args.check == "xhttp-gateway":
+ from .protocol_xhttp_gateway import main as xhttp_gateway
+
+ return xhttp_gateway(args.run_dir, identities_only=args.identities_only)
+ elif args.check == "protocol-coverage":
+ if args.catalog_only:
+ check_protocol_catalogs(CATALOG_DIR)
else:
- run_mihomo_interop(args.binary)
+ check_run(
+ args.run_dir.resolve(),
+ args.suite.upper(),
+ args.manifest,
+ )
+ elif args.check == "protocol-interop":
+ run_protocol_interop(
+ stage=args.suite.upper(),
+ identifiers=args.identifiers,
+ protocol=args.protocol,
+ list_only=args.list_only,
+ preflight_only=args.preflight_only,
+ run_dir=args.run_dir,
+ )
+ elif args.check == "reality-hybrid":
+ from .protocol_reality_hybrid import main as run_reality_hybrid
+
+ return run_reality_hybrid(args.run_dir, args.identifiers)
else:
check_tls_dependencies()
else:
- run_demo(args.config)
+ run_demo(args.config, xray_source=args.xray_source)
except (OSError, RuntimeError, ValueError, subprocess.SubprocessError) as error:
print(f"vcore-scripts: {error}", file=sys.stderr)
return 1
diff --git a/scripts/src/vcore_scripts/container_bandwidth_origin.py b/scripts/src/vcore_scripts/container_bandwidth_origin.py
new file mode 100644
index 0000000..d4adb2f
--- /dev/null
+++ b/scripts/src/vcore_scripts/container_bandwidth_origin.py
@@ -0,0 +1,105 @@
+"""Bounded one-way bandwidth origin, only inside the owned HYSTERIA2 container.
+
+64-KiB records carry a sequence and deterministic payload. Upload progress is
+timestamped at the actual origin, not inferred from the client's send buffer.
+"""
+
+import hashlib
+import os
+import select
+import socket
+import struct
+import sys
+import threading
+import time
+
+SIZE = 65536
+END = (1 << 64) - 1
+SLOTS = threading.BoundedSemaphore(4)
+
+
+def exact(stream, size):
+ value = bytearray()
+ while len(value) < size:
+ part = stream.recv(size - len(value))
+ if not part:
+ raise ValueError("truncated bandwidth record")
+ value.extend(part)
+ return bytes(value)
+
+
+def record(sequence):
+ return struct.pack("!Q", sequence) + bytes([sequence % 251]) * (SIZE - 8)
+
+
+def serve(control):
+ try:
+ with control, socket.socket() as listener:
+ control.settimeout(90)
+ direction = exact(control, 1)
+ if direction not in (b"U", b"D"):
+ raise ValueError("invalid bandwidth direction")
+ listener.bind(("0.0.0.0", 0))
+ listener.listen(1)
+ listener.settimeout(15)
+ control.sendall(struct.pack("!H", listener.getsockname()[1]))
+ stream, _ = listener.accept()
+ with stream:
+ stream.settimeout(30)
+ stream.sendall(b"ready")
+ digest, sequence = hashlib.sha256(), 0
+ started = time.monotonic_ns()
+ if direction == b"U":
+ while True:
+ data = exact(stream, SIZE)
+ number = struct.unpack("!Q", data[:8])[0]
+ if number == END:
+ break
+ if data != record(sequence):
+ raise ValueError("upload sequence or payload mismatch")
+ digest.update(data)
+ sequence += 1
+ control.sendall(
+ b"P"
+ + struct.pack(
+ "!QQ", sequence, time.monotonic_ns() - started
+ )
+ )
+ stream.sendall(b"done!")
+ else:
+ if exact(stream, 1) != b"S":
+ raise ValueError("missing start")
+ while True:
+ ready, _, _ = select.select([stream], [], [], 0)
+ if ready:
+ if exact(stream, 1) != b"X":
+ raise ValueError("invalid stop")
+ break
+ data = record(sequence)
+ stream.sendall(data)
+ digest.update(data)
+ sequence += 1
+ stream.sendall(record(END))
+ control.sendall(b"D" + struct.pack("!Q", sequence) + digest.digest())
+ except (OSError, ValueError) as error:
+ print(type(error).__name__, flush=True)
+ finally:
+ SLOTS.release()
+
+
+def main():
+ if sys.platform != "linux" or os.environ.get("VCORE_ISOLATED_ORIGIN") != "1":
+ raise SystemExit("isolated container required")
+ with socket.socket() as listener:
+ listener.bind(("0.0.0.0", 24002))
+ listener.listen(4)
+ while True:
+ control, _ = listener.accept()
+ if SLOTS.acquire(blocking=False):
+ threading.Thread(target=serve, args=(control,), daemon=True).start()
+ else:
+ control.close()
+
+
+if __name__ == "__main__":
+ main()
diff --git a/scripts/src/vcore_scripts/container_close_client.py b/scripts/src/vcore_scripts/container_close_client.py
new file mode 100644
index 0000000..1e4fe2e
--- /dev/null
+++ b/scripts/src/vcore_scripts/container_close_client.py
@@ -0,0 +1,74 @@
+"""Read a real official client's close behavior; execute only inside its VM lab."""
+
+import json
+import os
+import socket
+import ssl
+import struct
+import sys
+from pathlib import Path
+
+
+def exact(io, length):
+ data = bytearray()
+ while len(data) < length:
+ part = io.recv(length - len(data))
+ if not part:
+ raise ValueError("truncated close control")
+ data.extend(part)
+ return bytes(data)
+
+
+def main(proxy, origin, variant="plain"):
+ if sys.platform != "linux" or os.environ.get("VCORE_ISOLATED_ORIGIN") != "1":
+ raise RuntimeError("isolated close consumer required")
+ with socket.create_connection((origin, 24000), timeout=10) as control:
+ vision = variant == "vision-direct"
+ if variant not in ("plain", "vision-direct"):
+ raise ValueError("unknown close variant")
+ control.sendall(b"\x15" if vision else b"\x0b")
+ port = struct.unpack("!H", exact(control, 2))[0]
+ with socket.create_connection((proxy, 23002), timeout=10) as client:
+ client.sendall(b"\x05\x01\x00")
+ assert exact(client, 2) == b"\x05\x00"
+ client.sendall(
+ b"\x05\x01\x00\x01" + socket.inet_aton(origin) + struct.pack("!H", port)
+ )
+ header = exact(client, 4)
+ assert header[:3] == b"\x05\x00\x00"
+ exact(client, 6 if header[3] == 1 else 18)
+ io = client
+ if vision:
+ from tls_bio import TlsBio
+
+ context = ssl.create_default_context(
+ cafile=str(Path(__file__).with_name("cert.pem"))
+ )
+ context.minimum_version = ssl.TLSVersion.TLSv1_3
+ context.maximum_version = ssl.TLSVersion.TLSv1_3
+ io = TlsBio(client, context, server=False)
+ assert io.tls.version() == "TLSv1.3"
+ assert exact(control, 2) == b"A\x13"
+ assert exact(io, 5) == b"hello"
+ payload = b"Z" * 65536 if vision else b"ping"
+ io.sendall(payload)
+ assert exact(io, len(payload)) == payload
+ client.shutdown(socket.SHUT_WR)
+ tail = bytearray()
+ try:
+ while chunk := io.recv(1024):
+ tail.extend(chunk)
+ if len(tail) > 1024:
+ raise ValueError("close tail limit")
+ except ConnectionResetError:
+ pass
+ assert exact(control, 1 if vision else 2) == (b"D" if vision else b"AD")
+ print(
+ json.dumps(
+ {"tail_hex": tail.hex(), "terminated": True, "variant": variant}
+ )
+ )
+
+
+if __name__ == "__main__":
+ main(*sys.argv[1:])
diff --git a/scripts/src/vcore_scripts/container_quic_observer.py b/scripts/src/vcore_scripts/container_quic_observer.py
new file mode 100644
index 0000000..babdc75
--- /dev/null
+++ b/scripts/src/vcore_scripts/container_quic_observer.py
@@ -0,0 +1,56 @@
+"""Read-only, bounded native qlog observer for the isolated identity diagnostic.
+
+Return certificate failure categories only, never frames, keys, connection IDs,
+request headers or peer addresses. Raw qlogs stay in the disposable container.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+
+
+def summarize_trace(text):
+ failures = []
+ for line in text.splitlines(keepends=True):
+ if not line.endswith("\n"):
+ continue # The native writer can still be appending the last record.
+ row = json.loads(line.lstrip("\x1e"))
+ if row.get("name") != "transport:connection_closed":
+ continue
+ data = row.get("data", {})
+ code = data.get("connection_error", "")
+ if data.get("initiator") != "local" or not code.startswith("crypto_error_"):
+ continue
+ # RFC 9001 CRYPTO_ERROR = 0x100 + the RFC 8446 TLS alert number.
+ # quic-go's local crypto error deliberately leaves qlog.reason empty.
+ categories = {
+ "crypto_error_0x174": "certificate_required",
+ "crypto_error_0x12d": "certificate_expired",
+ "crypto_error_0x130": "unknown_ca",
+ }
+ category = categories.get(code)
+ if category:
+ failures.append({"tls_alert": code, "category": category})
+ return failures
+
+
+def main():
+ files = sorted(Path("/data/qlog").glob("*.sqlog"))
+ if len(files) > 128 or sum(path.stat().st_size for path in files) > 16 * 1024**2:
+ raise ValueError("native identity trace exceeded diagnostic bound")
+ print(
+ json.dumps(
+ {
+ hashlib.sha256(path.name.encode()).hexdigest(): summarize_trace(
+ path.read_text()
+ )
+ for path in files
+ }
+ )
+ )
+
+
+if __name__ == "__main__":
+ main()
diff --git a/scripts/src/vcore_scripts/container_reality_hybrid.py b/scripts/src/vcore_scripts/container_reality_hybrid.py
new file mode 100644
index 0000000..0393963
--- /dev/null
+++ b/scripts/src/vcore_scripts/container_reality_hybrid.py
@@ -0,0 +1,263 @@
+"""Container-only OpenSSL cover sites, TCP origin, and transparent observation."""
+
+import json
+import os
+import select
+import socket
+import ssl
+import sys
+import threading
+import time
+from pathlib import Path
+
+ROOT = Path("/data/fixture")
+EVENTS = Path("/data/events.jsonl")
+LOCK = threading.Lock()
+SLOTS = threading.BoundedSemaphore(32)
+
+
+def emit(**event):
+ with LOCK, EVENTS.open("a") as output:
+ if EVENTS.stat().st_size > 8 * 1024 * 1024:
+ raise ValueError("observer event limit")
+ output.write(json.dumps(event) + "\n")
+
+
+def exact(stream, size):
+ data = bytearray()
+ while len(data) < size:
+ part = stream.recv(size - len(data))
+ if not part:
+ raise EOFError()
+ data.extend(part)
+ return bytes(data)
+
+
+def word(data, at):
+ return int.from_bytes(data[at : at + 2], "big")
+
+
+def client_hello(stream):
+ wire, message = bytearray(), bytearray()
+ for _ in range(8):
+ head = exact(stream, 5)
+ size = word(head, 3)
+ if head[0] != 22 or not 1 <= size <= 16384:
+ raise ValueError("TLS record")
+ body = exact(stream, size)
+ wire.extend(head + body)
+ message.extend(body)
+ if len(message) > 65536:
+ raise ValueError("hello limit")
+ if len(message) >= 4:
+ expected = 4 + int.from_bytes(message[1:4], "big")
+ if message[0] != 1 or len(message) > expected:
+ raise ValueError("ClientHello length")
+ if len(message) == expected:
+ return bytes(wire), bytes(message)
+ raise ValueError("record count")
+
+
+def extensions(message, client):
+ at = 39 + message[38]
+ if client:
+ at += 2 + word(message, at)
+ at += 1 + message[at]
+ else:
+ at += 3
+ end = at + 2 + word(message, at)
+ at += 2
+ if end != len(message):
+ raise ValueError("extension length")
+ while at < end:
+ kind, size = word(message, at), word(message, at + 2)
+ data = message[at + 4 : at + 4 + size]
+ if len(data) != size:
+ raise ValueError("truncated extension")
+ yield kind, data
+ at += 4 + size
+
+
+def shares(message):
+ result = []
+ for kind, data in extensions(message, True):
+ if kind == 51:
+ at = 2
+ while at < len(data):
+ group, size = word(data, at), word(data, at + 2)
+ if group & 0x0F0F != 0x0A0A:
+ result.append([group, size])
+ at += 4 + size
+ if at != len(data):
+ raise ValueError("key share length")
+ return result
+
+
+def selected_group(wire):
+ if len(wire) < 5 or len(wire) < 5 + word(wire, 3):
+ return None
+ if wire[0] != 22 or wire[5] != 2:
+ return -1
+ message = wire[5 : 5 + word(wire, 3)]
+ size = 4 + int.from_bytes(message[1:4], "big")
+ for kind, data in extensions(message[:size], False):
+ if kind == 51:
+ return word(data, 0)
+ return -1
+
+
+def handle(stream, port, context):
+ try:
+ with stream:
+ stream.settimeout(5)
+ if port == 9000:
+ # Readiness opens a connection without application data.
+ received = 0
+ while part := stream.recv(16384):
+ if not received:
+ emit(port=port, event="origin-data")
+ received += len(part)
+ if received > 10 * 1024 * 1024:
+ raise ValueError("origin byte limit")
+ stream.sendall(part)
+ if received:
+ emit(port=port, event="origin-complete", bytes=received)
+ return
+ try:
+ raw, hello = client_hello(stream)
+ except EOFError:
+ return
+ emit(
+ port=port,
+ event="client-hello",
+ shares=shares(hello),
+ groups=[
+ word(data, at)
+ for kind, data in extensions(hello, True)
+ if kind == 10
+ for at in range(2, len(data), 2)
+ if word(data, at) & 0x0F0F != 0x0A0A
+ ],
+ )
+ if context is None:
+ address = json.loads((ROOT / "routes.json").read_text())[str(port)]
+ with socket.create_connection(tuple(address), timeout=5) as upstream:
+ upstream.sendall(raw)
+ deadline, total = time.monotonic() + 240, len(raw)
+ flight, observed = bytearray(), False
+ while time.monotonic() < deadline:
+ ready, _, _ = select.select([stream, upstream], [], [], 0.2)
+ for source in ready:
+ data = source.recv(16384)
+ if not data:
+ if source is upstream:
+ emit(
+ port=port,
+ event="server-close",
+ bytes=len(flight),
+ )
+ return
+ total += len(data)
+ if total > 128 * 1024 * 1024:
+ raise ValueError("relay byte limit")
+ if source is upstream and not observed:
+ flight.extend(data)
+ if len(flight) > 65536:
+ raise ValueError("server flight limit")
+ group = selected_group(flight)
+ if group is not None:
+ emit(
+ port=port,
+ event="server-hello"
+ if group >= 0
+ else "tls-response",
+ group=group,
+ hrr=flight[11:43]
+ == bytes.fromhex(
+ "cf21ad74e59a6111be1d8c021e65b891"
+ "c2a211167abb8c5e079e09e2c8a8339c"
+ ),
+ )
+ observed = True
+ (upstream if source is stream else stream).sendall(data)
+ raise TimeoutError("relay duration")
+ incoming, outgoing = ssl.MemoryBIO(), ssl.MemoryBIO()
+ tls = context.wrap_bio(incoming, outgoing, server_side=True)
+ incoming.write(raw)
+ for _ in range(32):
+ try:
+ tls.do_handshake()
+ stream.sendall(outgoing.read())
+ emit(port=port, event="cover-complete", version=tls.version())
+ return
+ except ssl.SSLWantReadError:
+ data = outgoing.read()
+ if data:
+ stream.sendall(data)
+ data = stream.recv(16384)
+ if not data:
+ return
+ incoming.write(data)
+ raise ValueError("cover iteration limit")
+ except ssl.SSLError as error:
+ emit(
+ port=port,
+ event="no-shared-group"
+ if error.reason == "NO_SUITABLE_KEY_SHARE"
+ else "closed",
+ )
+ except (OSError, ValueError, EOFError):
+ emit(port=port, event="closed")
+ finally:
+ SLOTS.release()
+
+
+def serve(port, context):
+ with socket.socket(socket.AF_INET6) as listener:
+ listener.setsockopt(socket.IPPROTO_IPV6, socket.IPV6_V6ONLY, 0)
+ listener.bind(("::", port))
+ listener.listen(32)
+ while True:
+ stream, _ = listener.accept()
+ SLOTS.acquire()
+ threading.Thread(
+ target=handle, args=(stream, port, context), daemon=True
+ ).start()
+
+
+if __name__ == "__main__":
+ if sys.platform != "linux" or os.environ.get("VCORE_ISOLATED_ORIGIN") != "1":
+ raise SystemExit("isolated REALITY observer required")
+ EVENTS.touch()
+ contexts = {}
+ for port, group, version in [
+ (24431, "X25519MLKEM768", ssl.TLSVersion.TLSv1_3),
+ (24432, "X25519", ssl.TLSVersion.TLSv1_3),
+ (24433, "secp384r1", ssl.TLSVersion.TLSv1_3),
+ (24434, "X25519", ssl.TLSVersion.TLSv1_2),
+ ]:
+ context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+ context.load_cert_chain(ROOT / "cert.pem", ROOT / "key.pem")
+ # Python's EC-NID setter rejects hybrid group names even with OpenSSL
+ # 3.5. Use the native default list for the hybrid cover, then verify the
+ # actual ServerHello/finished connection selected 4588 in the harness.
+ if group != "X25519MLKEM768":
+ context.set_ecdh_curve(group)
+ context.minimum_version = context.maximum_version = version
+ context.set_alpn_protocols(["h2", "http/1.1"])
+ contexts[port] = context
+ emit(event="native-tls", version=ssl.OPENSSL_VERSION)
+ threads = [
+ threading.Thread(target=serve, args=(port, context))
+ for port, context in [
+ *contexts.items(),
+ *(
+ (int(port), None)
+ for port in json.loads((ROOT / "routes.json").read_text())
+ ),
+ ]
+ ]
+ for thread in threads:
+ thread.start()
+ for thread in threads:
+ thread.join()
diff --git a/scripts/src/vcore_scripts/container_tls_bio.py b/scripts/src/vcore_scripts/container_tls_bio.py
new file mode 100644
index 0000000..466ad16
--- /dev/null
+++ b/scripts/src/vcore_scripts/container_tls_bio.py
@@ -0,0 +1,48 @@
+"""Fixture-only public OpenSSL MemoryBIO driver; never a TLS implementation."""
+
+import ssl
+
+
+class TlsBio:
+ def __init__(self, stream, context, *, server):
+ self.stream = stream
+ self.incoming = ssl.MemoryBIO()
+ self.outgoing = ssl.MemoryBIO()
+ self.tls = context.wrap_bio(
+ self.incoming,
+ self.outgoing,
+ server_side=server,
+ server_hostname=None if server else "localhost",
+ )
+ self.perform(self.tls.do_handshake)
+
+ def flush(self):
+ while self.outgoing.pending:
+ self.stream.sendall(self.outgoing.read())
+
+ def perform(self, operation, *args):
+ while True:
+ try:
+ result = operation(*args)
+ self.flush()
+ return result
+ except ssl.SSLWantWriteError:
+ self.flush()
+ except ssl.SSLWantReadError:
+ self.flush()
+ chunk = self.stream.recv(65536)
+ if chunk:
+ self.incoming.write(chunk)
+ else:
+ self.incoming.write_eof()
+
+ def recv(self, length):
+ try:
+ return self.perform(self.tls.read, length)
+ except (ssl.SSLEOFError, ssl.SSLZeroReturnError):
+ return b""
+
+ def sendall(self, data):
+ offset = 0
+ while offset < len(data):
+ offset += self.perform(self.tls.write, data[offset:])
diff --git a/scripts/src/vcore_scripts/container_tls_observer.py b/scripts/src/vcore_scripts/container_tls_observer.py
new file mode 100644
index 0000000..8f20fc1
--- /dev/null
+++ b/scripts/src/vcore_scripts/container_tls_observer.py
@@ -0,0 +1,179 @@
+"""Container-only TLS observer; never decodes or serves a proxy protocol."""
+
+from __future__ import annotations
+
+import base64
+import contextlib
+import json
+import os
+import socket
+import ssl
+import threading
+import time
+from pathlib import Path
+
+
+def capture_client_hello(receive):
+ """Read at most eight records and 64 KiB of ClientHello from injected IO."""
+
+ def exact(count):
+ result = bytearray()
+ while len(result) < count:
+ part = receive(count - len(result))
+ if not part:
+ raise EOFError("incomplete TLS record")
+ result.extend(part)
+ return bytes(result)
+
+ records, handshake, layout = bytearray(), bytearray(), []
+ for _ in range(8):
+ header = exact(5)
+ size = int.from_bytes(header[3:], "big")
+ if header[0] != 22 or not 1 <= size <= 18432:
+ raise ValueError("expected bounded handshake record")
+ payload = exact(size)
+ records.extend(header + payload)
+ handshake.extend(payload)
+ layout.append(
+ dict(type=header[0], version=int.from_bytes(header[1:3], "big"), bytes=size)
+ )
+ if len(handshake) >= 4:
+ hello_size = int.from_bytes(handshake[1:4], "big") + 4
+ if handshake[0] != 1 or hello_size > 65536:
+ raise ValueError("expected bounded ClientHello")
+ if len(handshake) >= hello_size:
+ return bytes(records), bytes(handshake[:hello_size]), layout
+ raise ValueError("ClientHello record limit")
+
+
+def main():
+ if os.environ.get("VCORE_ISOLATED_TLS_OBSERVER") != "1":
+ raise RuntimeError("TLS observer requires an owned isolated container")
+ log = Path("/data/events.jsonl")
+ lock, stop = threading.Lock(), threading.Event()
+ deadline = time.monotonic() + 900
+ log.touch()
+
+ def emit(event):
+ with lock:
+ if log.stat().st_size > 8 * 1024 * 1024:
+ stop.set()
+ raise RuntimeError("observer output limit")
+ with log.open("a") as output:
+ output.write(json.dumps(event, separators=(",", ":")) + "\n")
+
+ contexts = {24430: None}
+ for port, version in (
+ (24431, ssl.TLSVersion.TLSv1_3),
+ (24432, ssl.TLSVersion.TLSv1_2),
+ ):
+ context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+ context.load_cert_chain("/data/fixture/cert.pem", "/data/fixture/key.pem")
+ context.minimum_version = context.maximum_version = version
+ context.set_alpn_protocols(["h2", "http/1.1"])
+ contexts[port] = context
+
+ def serve(port, context):
+ try:
+ with socket.socket() as listener:
+ listener.settimeout(0.5)
+ listener.bind(("0.0.0.0", port))
+ listener.listen(8)
+ sequence = 0
+ while not stop.is_set() and time.monotonic() < deadline:
+ try:
+ stream, _ = listener.accept()
+ except TimeoutError:
+ continue
+ sequence += 1
+ if sequence > 512:
+ raise RuntimeError("observer connection limit")
+ with stream:
+ stream.settimeout(5)
+ event = dict(port=port, sequence=sequence)
+ try:
+ raw, hello, layout = capture_client_hello(stream.recv)
+ except EOFError:
+ continue # The readiness connect carries no TLS bytes.
+ except (OSError, ValueError) as error:
+ emit(
+ event
+ | dict(
+ status="capture-error", reason=type(error).__name__
+ )
+ )
+ continue
+ event.update(
+ client_hello_b64=base64.b64encode(hello).decode(),
+ records_b64=base64.b64encode(raw).decode(),
+ records=layout,
+ )
+ if context is None:
+ emit(event | dict(status="captured-only"))
+ with contextlib.suppress(OSError):
+ stream.sendall(bytes.fromhex("15030300020228"))
+ continue
+ incoming, outgoing = ssl.MemoryBIO(), ssl.MemoryBIO()
+ tls = context.wrap_bio(incoming, outgoing, server_side=True)
+ incoming.write(raw)
+ try:
+ consumed = len(raw)
+ for _ in range(32):
+ try:
+ tls.do_handshake()
+ stream.sendall(outgoing.read())
+ emit(
+ event
+ | dict(
+ status="tls-handshake-complete",
+ version=tls.version(),
+ cipher=tls.cipher()[0],
+ alpn=tls.selected_alpn_protocol(),
+ resumed=tls.session_reused,
+ )
+ )
+ break
+ except ssl.SSLWantReadError:
+ stream.sendall(outgoing.read())
+ chunk = stream.recv(16384)
+ if not chunk:
+ raise EOFError() from None
+ consumed += len(chunk)
+ if consumed > 131072:
+ raise ValueError(
+ "TLS handshake input limit"
+ ) from None
+ incoming.write(chunk)
+ else:
+ raise ValueError("TLS handshake iteration limit")
+ except (OSError, EOFError, ValueError) as error:
+ with contextlib.suppress(OSError):
+ stream.sendall(outgoing.read())
+ emit(
+ event
+ | dict(
+ status="tls-handshake-rejected",
+ reason=getattr(
+ error, "reason", type(error).__name__
+ ),
+ )
+ )
+ except BaseException as error:
+ emit(dict(status="observer-error", reason=type(error).__name__))
+ stop.set()
+
+ workers = [
+ threading.Thread(target=serve, args=(port, ctx))
+ for port, ctx in contexts.items()
+ ]
+ print(
+ json.dumps(dict(openssl=ssl.OPENSSL_VERSION, ports=list(contexts))), flush=True
+ )
+ for worker in workers:
+ worker.start()
+ for worker in workers:
+ worker.join()
+
+
+if __name__ == "__main__":
+ main()
diff --git a/scripts/src/vcore_scripts/container_udp_origin.py b/scripts/src/vcore_scripts/container_udp_origin.py
new file mode 100644
index 0000000..27d4a85
--- /dev/null
+++ b/scripts/src/vcore_scripts/container_udp_origin.py
@@ -0,0 +1,286 @@
+"""Bounded UDP echo origin, run only inside the owned fixture container.
+
+A TCP observer allocates one UDP association with a one-byte address family.
+The response starts with its two-byte UDP port. Each real datagram is reported
+as length/source-port (two network-order u16s), then the exact payload. Echoes
+are sent by this container, never by the host test driver.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import select
+import socket
+import ssl
+import struct
+import sys
+import threading
+import time
+
+CAPACITY = 20000
+INTEGRATION_PROFILE = os.environ.get("VCORE_ORIGIN_PROFILE") == "INTEGRATION"
+# Explicit, still bounded pressure profile. Historical protocol fixtures keep
+# their original limits; no production queue or socket policy is changed.
+SLOTS = threading.BoundedSemaphore(96 if INTEGRATION_PROFILE else 8)
+COVER_SLOTS = threading.BoundedSemaphore(8)
+
+
+def receive_exact(stream, size):
+ data = bytearray()
+ while len(data) < size:
+ chunk = stream.recv(min(65536, size - len(data)))
+ if not chunk:
+ raise ValueError("truncated fixture request")
+ data.extend(chunk)
+ return bytes(data)
+
+
+def serve_tcp(control, mode, ipv6=False):
+ """10=bulk/server-first, 11=close differential, 12=identity probe.
+
+ Observer A proves an actual accept; D proves exact request bytes and normal
+ completion. Rejected identities must produce neither. No host-side server.
+ """
+ with socket.socket(
+ socket.AF_INET6 if ipv6 else socket.AF_INET, socket.SOCK_STREAM
+ ) as listener:
+ if ipv6:
+ listener.setsockopt(socket.IPPROTO_IPV6, socket.IPV6_V6ONLY, 1)
+ listener.bind(("::" if ipv6 else "0.0.0.0", 0))
+ listener.listen(8)
+ control.sendall(struct.pack("!H", listener.getsockname()[1]))
+ for _ in range(32):
+ ready, _, _ = select.select([control, listener], [], [], 30)
+ if not ready or control in ready:
+ return
+ stream, _ = listener.accept()
+ control.sendall(b"A")
+ if mode == 21:
+ # Generate the withheld tail with the real TLS engine before
+ # transport EOF. This tests FIN semantics without depending on
+ # OpenSSL accepting an application write after a ragged EOF.
+ from tls_bio import TlsBio
+
+ with stream:
+ stream.settimeout(15)
+ tls = TlsBio(
+ stream, tls_context(ssl.TLSVersion.TLSv1_3), server=True
+ )
+ assert tls.tls.version() == "TLSv1.3"
+ control.sendall(b"\x13")
+ tls.sendall(b"hello")
+ data = receive_exact(tls, 65536)
+ if data != b"Z" * 65536:
+ raise ValueError("TLS direct close data")
+ tls.sendall(data)
+ tail = b"native-after-upload-eof"
+ assert tls.tls.write(tail) == len(tail)
+ if stream.recv(1):
+ raise ValueError("unexpected data after TLS direct request")
+ with contextlib.suppress(OSError):
+ tls.flush()
+ control.sendall(b"D")
+ continue
+ if mode in (16, 18):
+ context = tls_context(
+ ssl.TLSVersion.TLSv1_3 if mode == 16 else ssl.TLSVersion.TLSv1_2
+ )
+ stream.settimeout(15)
+ stream = context.wrap_socket(stream, server_side=True)
+ control.sendall(b"\x13" if stream.version() == "TLSv1.3" else b"\x12")
+ with stream:
+ stream.settimeout(15)
+ if mode == 13: # bounded-lifetime echo; client-first and cancellation
+ while data := stream.recv(65536):
+ stream.sendall(data)
+ elif mode == 14: # measureDelay/HTTP entrypoint, not a proxy decoder
+ request = bytearray()
+ while not request.endswith(b"\r\n\r\n"):
+ request.extend(receive_exact(stream, 1))
+ if len(request) > 16384:
+ raise ValueError("HTTP origin header limit")
+ stream.sendall(
+ b"HTTP/1.1 200 OK\r\nConnection: close\r\n"
+ b"Content-Length: 0\r\n\r\n"
+ )
+ elif mode == 15: # deliberately withhold all handshake replies
+ while stream.recv(65536):
+ pass
+ elif mode == 12:
+ if receive_exact(stream, 15) != b"synthetic-probe":
+ raise ValueError("identity probe data")
+ stream.sendall(b"ok")
+ else:
+ stream.sendall(b"hello")
+ if mode in (10, 16, 18):
+ data = receive_exact(stream, 10 * 1024 * 1024)
+ if data != b"\x5a" * len(data):
+ raise ValueError("bulk data")
+ stream.sendall(data + b"trailer")
+ else:
+ data = receive_exact(stream, 4)
+ if data != b"ping":
+ raise ValueError("close probe data")
+ stream.sendall(data)
+ if stream.recv(1):
+ raise ValueError("unexpected data after request")
+ if mode == 11:
+ # Whole-close peers need not accept a tail.
+ with contextlib.suppress(OSError):
+ stream.sendall(b"native-after-upload-eof")
+ control.sendall(b"D")
+
+
+def serve(control):
+ try:
+ with control:
+ control.settimeout(15)
+ control.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+ family = control.recv(1)
+ if family and (family[0] & 0x7F) in (*range(10, 17), 18, 21):
+ serve_tcp(control, family[0] & 0x7F, bool(family[0] & 0x80))
+ return
+ if family not in (b"\x04", b"\x06", b"\x11", b"\x13", b"\x14"):
+ return
+ ipv6 = family == b"\x06"
+ with socket.socket(
+ socket.AF_INET6 if ipv6 else socket.AF_INET, socket.SOCK_DGRAM
+ ) as udp:
+ if ipv6:
+ udp.setsockopt(socket.IPPROTO_IPV6, socket.IPV6_V6ONLY, 1)
+ udp.bind(("::" if ipv6 else "0.0.0.0", 0))
+ control.sendall(struct.pack("!H", udp.getsockname()[1]))
+ peer_ipv4 = (
+ socket.inet_ntop(socket.AF_INET, receive_exact(control, 4))
+ if family == b"\x13"
+ else None
+ )
+ seen = False
+ dns = family in (b"\x11", b"\x13")
+ dns_deadline = time.monotonic() + 240
+ for _ in range(100000 if INTEGRATION_PROFILE else 20000):
+ wait = (
+ min(30, max(0, dns_deadline - time.monotonic())) if dns else 30
+ )
+ if not wait:
+ return
+ ready, _, _ = select.select([control, udp], [], [], wait)
+ if control in ready:
+ return # EOF/cancel closes this association's UDP socket.
+ if not ready:
+ if dns:
+ # Runtime-owned DNS can be quiet during TCP or an
+ # IP-only UDP phase. Keep it until control closes,
+ # within the same bounded 240-second fixture lifetime.
+ continue
+ return
+ packet, source = udp.recvfrom(CAPACITY + 1)
+ if len(packet) > CAPACITY:
+ return
+ if family == b"\x14":
+ # A native origin blackhole, not a protocol peer. Report
+ # only first receipt; all handshake bytes are discarded.
+ if not seen:
+ control.sendall(b"A")
+ seen = True
+ continue
+ control.sendall(struct.pack("!HH", len(packet), source[1]) + packet)
+ response = (
+ dns_response(packet, control.getsockname()[0], peer_ipv4)
+ if family in (b"\x11", b"\x13")
+ else packet
+ )
+ if udp.sendto(response, source) != len(response):
+ return
+ except (OSError, ValueError):
+ # Client cancellation/failed association is recorded by the test driver.
+ pass
+ finally:
+ SLOTS.release()
+
+
+def dns_response(packet, ipv4, peer_ipv4=None):
+ """Only the synthetic business name is answerable; never system DNS."""
+ question = b"\x0dvcore-fixture\x04test\x00"
+ peer_question = b"\x04peer\x07fixture\x04test\x00"
+ if peer_ipv4 and packet[12 : 12 + len(peer_question)] == peer_question:
+ question, ipv4 = peer_question, peer_ipv4
+ if (
+ len(packet) < 12 + len(question) + 4
+ or packet[12 : 12 + len(question)] != question
+ ):
+ raise ValueError("unexpected DNS question (including magic names)")
+ qtype = struct.unpack("!H", packet[-4:-2])[0]
+ answer = socket.inet_pton(socket.AF_INET, ipv4) if qtype == 1 else b""
+ response = bytearray(packet)
+ response[2:4] = b"\x81\x80"
+ response[6:8] = struct.pack("!H", int(bool(answer)))
+ if answer:
+ response.extend(b"\xc0\x0c\x00\x01\x00\x01\x00\x00\x00\x00\x00\x04" + answer)
+ return bytes(response)
+
+
+def tls_context(version):
+ context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+ context.minimum_version = version
+ context.maximum_version = version
+ context.set_ecdh_curve("X25519")
+ context.load_cert_chain(
+ os.environ["VCORE_ORIGIN_CERT"], os.environ["VCORE_ORIGIN_KEY"]
+ )
+ context.set_alpn_protocols(["h2", "http/1.1"])
+ context.num_tickets = 0
+ return context
+
+
+def serve_camouflage(stream, context):
+ try:
+ with stream:
+ stream.settimeout(5)
+ with context.wrap_socket(stream, server_side=True) as secured:
+ secured.recv(1)
+ except OSError:
+ pass
+ finally:
+ COVER_SLOTS.release()
+
+
+def camouflage():
+ """Container-only TLS 1.3 target for REALITY authentication."""
+ context = tls_context(ssl.TLSVersion.TLSv1_3)
+ with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as listener:
+ listener.bind(("0.0.0.0", 24001))
+ listener.listen(8)
+ while True:
+ stream, _ = listener.accept()
+ # Independent XHTTP legs need concurrent cover handshakes. A quiet
+ # first leg must not hold the accept loop for its five-second bound.
+ if not COVER_SLOTS.acquire(blocking=False):
+ stream.close()
+ continue
+ threading.Thread(
+ target=serve_camouflage, args=(stream, context), daemon=True
+ ).start()
+
+
+def main():
+ if sys.platform != "linux" or os.environ.get("VCORE_ISOLATED_ORIGIN") != "1":
+ raise SystemExit(
+ "BLOCKED: this origin must be launched by the container harness"
+ )
+ if os.environ.get("VCORE_ORIGIN_CERT"):
+ threading.Thread(target=camouflage, daemon=True).start()
+ with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as listener:
+ listener.bind(("0.0.0.0", 24000))
+ listener.listen(8)
+ while True:
+ control, _ = listener.accept()
+ if not SLOTS.acquire(blocking=False):
+ control.close()
+ continue
+ threading.Thread(target=serve, args=(control,), daemon=True).start()
+
+
+if __name__ == "__main__":
+ main()
diff --git a/scripts/src/vcore_scripts/core_checks.py b/scripts/src/vcore_scripts/core_checks.py
new file mode 100644
index 0000000..199fbcd
--- /dev/null
+++ b/scripts/src/vcore_scripts/core_checks.py
@@ -0,0 +1,168 @@
+"""Memory-only checks shared by local development and CI.
+
+Network consumers remain explicit container suites. Keep this allowlist independent
+of historical milestone runners: compiling all targets is safe; executing them is not.
+"""
+
+from __future__ import annotations
+
+import re
+
+from .builds import CORE_DIR, DEFAULT_FEATURES
+from .protocol_peers import run_command
+
+FEATURE_TEST = (
+ "runtime::tests::integration_feature_admission_is_explicit_without_opening_sockets"
+)
+PROTOCOLS = ("socks5", "anytls", "shadowsocks", "trojan", "vmess", "vless", "hysteria2")
+TARGETS = (
+ "ech_config",
+ "ech_tls",
+ "encryption_config",
+ "reality_config",
+ "jls_config",
+ "security_capabilities",
+ "retired_security",
+ "feature_foundations",
+ "limit_foundations",
+ "trojan",
+ "trojan_config",
+ "vmess_config",
+ "vless_config",
+ "vless_lifecycle",
+ "xhttp_config",
+ "xhttp_budget",
+ "h2_stream_regression",
+ "stream_foundations",
+ "stream_shutdown",
+ "xhttp_h3_shutdown",
+ "hysteria2_paths",
+ "hysteria2_config",
+ "shadowsocks_backpressure",
+ "hysteria2_packet_ids",
+)
+LIB_FILTERS = (
+ "security::",
+ "outbound::vless::encryption",
+ "config::",
+ "outbound::hysteria2::",
+ "outbound::shadowsocks::tests::official_tcp_",
+ "outbound::anytls::",
+ "transport::h2_write::tests::",
+ "transport::sing_mux::smux_driver::tests::",
+ "transport::sing_mux::tests::",
+)
+EXACT_LIB_TESTS = (
+ "outbound::connector::tests::authenticated_continuation_keeps_group_choice_but_has_a_new_io_deadline",
+ FEATURE_TEST,
+ "ffi::tests::runtime_thread_cannot_reenter_invoke",
+ "ffi::tests::null_invalid_utf8_and_oversized_input_return_json_failures",
+ "ffi::tests::same_instance_command_is_fail_fast",
+ "ffi::tests::android_protector_is_required_only_for_tun",
+)
+
+
+def commands(profile: str) -> list[list[str]]:
+ cargo = ["cargo", "test", "--locked", "--all-features"]
+ if profile in {"debug", "release"}:
+ if profile == "release":
+ cargo += ["--release"]
+ return [
+ cargo + [arg for target in TARGETS for arg in ("--test", target)],
+ *(cargo + ["--lib", name] for name in LIB_FILTERS),
+ *(cargo + ["--lib", name, "--", "--exact"] for name in EXACT_LIB_TESTS),
+ cargo
+ + [
+ "--test",
+ "quic_datagram_foundations",
+ "pending_send_is_not_restarted_and_stop_cancels_without_waiting_for_writable",
+ "--",
+ "--exact",
+ ],
+ ]
+ if profile == "features":
+ features = ["outbound-" + protocol for protocol in PROTOCOLS]
+ return (
+ [
+ ["cargo", "check", "--locked", "--no-default-features", "--lib"]
+ + (["--features", name] if name else [])
+ for name in [
+ "",
+ *features,
+ "stream-transport",
+ "quic-transport",
+ "tun",
+ "ffi",
+ ]
+ ]
+ + [
+ [
+ "cargo",
+ "test",
+ "--locked",
+ "--no-default-features",
+ "--features",
+ name,
+ "--lib",
+ FEATURE_TEST,
+ "--",
+ "--exact",
+ ]
+ for name in features
+ ]
+ + [
+ [
+ "cargo",
+ "test",
+ "--locked",
+ "--no-default-features",
+ "--test",
+ "feature_foundations",
+ "--test",
+ "hysteria2_config",
+ ],
+ ["cargo", "check", "--locked", "--lib"],
+ cargo + ["--all-targets", "--no-run"],
+ [
+ "cargo",
+ "build",
+ "--locked",
+ "--release",
+ "--no-default-features",
+ "--features",
+ DEFAULT_FEATURES,
+ "--lib",
+ ],
+ ]
+ )
+ raise ValueError("unknown core check profile")
+
+
+def validate_execution(
+ command: list[str], output: str, returncode: int, cleanup: bool
+) -> None:
+ if returncode != 0 or not cleanup:
+ raise RuntimeError("core check failed, timed out, or did not join its process")
+ if command[:2] != ["cargo", "test"] or "--no-run" in command:
+ return
+ summaries = re.findall(
+ r"test result: ok\. (\d+) passed; (\d+) failed; \d+ ignored;", output
+ )
+ expected = max(1, command.count("--test"))
+ if len(summaries) != expected or any(
+ int(passed) == 0 or int(failed) for passed, failed in summaries
+ ):
+ raise RuntimeError(
+ "core check selected no tests or returned incomplete test results"
+ )
+
+
+def run(profile: str, *, list_only: bool = False) -> None:
+ for command in commands(profile):
+ print(" ".join(command), flush=True)
+ if list_only:
+ continue
+ result = run_command(command, cwd=CORE_DIR, timeout=3600, limit=4 * 1024 * 1024)
+ output = result.stdout.decode("utf-8", errors="replace")
+ print(output, end="", flush=True)
+ validate_execution(command, output, result.returncode, result.cleanup)
diff --git a/scripts/src/vcore_scripts/mihomo.py b/scripts/src/vcore_scripts/mihomo.py
index 41097f2..96ce408 100644
--- a/scripts/src/vcore_scripts/mihomo.py
+++ b/scripts/src/vcore_scripts/mihomo.py
@@ -15,7 +15,7 @@ from contextlib import ExitStack
from pathlib import Path
from .builds import CORE_DIR
-from .mihomo_isolation import exclusive_run, reserve_port
+from .mihomo_isolation import reserve_port
def _stop_peer(peer: subprocess.Popen) -> None:
@@ -41,32 +41,6 @@ def _wait_ready(peer, port: int, host: str = "127.0.0.1") -> None:
raise RuntimeError("mihomo did not become ready within 10 seconds")
-def run_mihomo_interop(
- binary: Path | None = None,
- *,
- extended: bool = False,
- soak_seconds: int = 0,
- container_binary: Path | None = None,
-) -> None:
- if not 0 <= soak_seconds <= 7200 or (soak_seconds and not extended):
- raise ValueError("soak seconds must be 0..7200 and require --extended")
- binary = (
- binary
- or Path(os.environ.get("VCORE_MIHOMO_BIN", CORE_DIR / "references/mihomo-test"))
- ).resolve()
- if not binary.is_file():
- raise RuntimeError(
- "mihomo binary is missing; build the reference or pass --binary (NOT RUN)"
- )
- with exclusive_run():
- _run_mihomo_interop(
- binary,
- extended=extended,
- soak_seconds=soak_seconds,
- container_binary=container_binary,
- )
-
-
def _run_mihomo_interop(
binary: Path,
*,
@@ -320,25 +294,44 @@ def _run_mihomo_interop(
if containers:
environment.update(containers.environment())
try:
- subprocess.run(
- [
- "cargo",
- "test",
- "--locked",
- "--features",
- "ffi",
- "--test",
- "mihomo_interop",
- "--",
- "--ignored",
- "--nocapture",
- "--test-threads=1",
- ],
- cwd=CORE_DIR,
- env=environment,
- check=True,
- timeout=300 + soak_seconds,
- )
+ command = [
+ "cargo",
+ "test",
+ "--locked",
+ "--features",
+ "ffi,interop-test" if os.environ.get("VCORE_CASE_EVENTS") else "ffi",
+ "--test",
+ "mihomo_interop",
+ "public_client_inbounds_interoperate_with_mihomo_in_both_directions",
+ "--",
+ "--exact",
+ "--ignored",
+ "--nocapture",
+ "--test-threads=1",
+ ]
+ if os.environ.get("VCORE_CASE_EVENTS"):
+ from .protocol_peers import run_command
+
+ completed = run_command(
+ command,
+ cwd=CORE_DIR,
+ env=environment,
+ timeout=300 + soak_seconds,
+ limit=4 * 1024 * 1024,
+ )
+ print(completed.stdout.decode("utf-8", errors="replace"), flush=True)
+ if completed.returncode != 0 or not completed.cleanup:
+ raise subprocess.CalledProcessError(
+ completed.returncode or 1, command
+ )
+ else:
+ subprocess.run(
+ command,
+ cwd=CORE_DIR,
+ env=environment,
+ check=True,
+ timeout=300 + soak_seconds,
+ )
except (subprocess.CalledProcessError, subprocess.TimeoutExpired):
for index in range(len(configs)):
print(f"Generated fixture peer {index} diagnostics (last 4096 bytes):")
diff --git a/scripts/src/vcore_scripts/mihomo_isolation.py b/scripts/src/vcore_scripts/mihomo_isolation.py
index 084d4a1..91dba04 100644
--- a/scripts/src/vcore_scripts/mihomo_isolation.py
+++ b/scripts/src/vcore_scripts/mihomo_isolation.py
@@ -19,6 +19,9 @@ class PortReservation:
# IPv4-only peers take these ports; IPv6 guards remain owned until exit.
self.ipv4.close()
+ def release_ipv6(self) -> None:
+ self.ipv6.close()
+
def close(self) -> None:
self.ipv4.close()
self.ipv6.close()
diff --git a/scripts/src/vcore_scripts/mihomo_release.py b/scripts/src/vcore_scripts/mihomo_release.py
new file mode 100644
index 0000000..92ea78b
--- /dev/null
+++ b/scripts/src/vcore_scripts/mihomo_release.py
@@ -0,0 +1,231 @@
+"""Download the latest official Mihomo release for interop tests without an API."""
+
+from __future__ import annotations
+
+import gzip
+import hashlib
+import http.client
+import io
+import os
+import platform
+import re
+import stat
+import tempfile
+import time
+import urllib.parse
+import urllib.request
+import zipfile
+import zlib
+from contextlib import contextmanager
+from pathlib import Path, PurePosixPath
+
+from .builds import CORE_DIR
+
+LATEST_VERSION_URL = (
+ "https://github.com/MetaCubeX/mihomo/releases/latest/download/version.txt"
+)
+RELEASE_URL = "https://github.com/MetaCubeX/mihomo/releases/download"
+SUPPORTED_TARGETS = (
+ "darwin-arm64",
+ "darwin-amd64",
+ "linux-arm64",
+ "linux-amd64",
+ "windows-arm64",
+ "windows-amd64",
+)
+MAX_VERSION_BYTES = 128
+MAX_ARCHIVE_BYTES = 128 * 1024 * 1024
+MAX_BINARY_BYTES = 256 * 1024 * 1024
+CHUNK_BYTES = 64 * 1024
+TRANSFER_SECONDS = 180
+
+
+def _target(target: str | None) -> str:
+ if target is None:
+ system = platform.system().lower()
+ machine = platform.machine().lower()
+ architecture = {
+ "arm64": "arm64",
+ "aarch64": "arm64",
+ "amd64": "amd64",
+ "x86_64": "amd64",
+ }.get(machine, machine)
+ target = f"{system}-{architecture}"
+ if target not in SUPPORTED_TARGETS:
+ raise RuntimeError(f"unsupported official mihomo target: {target}")
+ return target
+
+
+def _release_tag(tag: str) -> str:
+ if (
+ not isinstance(tag, str)
+ or re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]{0,127}", tag) is None
+ ):
+ raise RuntimeError("invalid official mihomo download tag")
+ return tag
+
+
+def _copy_and_hash(source, output, limit: int) -> str:
+ digest = hashlib.sha256()
+ total = 0
+ deadline = time.monotonic() + TRANSFER_SECONDS
+ # read1 avoids waiting for a complete chunk before checking the deadline.
+ read = getattr(source, "read1", source.read)
+ while True:
+ if time.monotonic() > deadline:
+ raise RuntimeError("official mihomo transfer exceeded its time limit")
+ chunk = read(min(CHUNK_BYTES, limit - total + 1))
+ if not chunk:
+ break
+ total += len(chunk)
+ if total > limit:
+ raise RuntimeError("official mihomo payload exceeded its size limit")
+ digest.update(chunk)
+ output.write(chunk)
+ if not total:
+ raise RuntimeError("official mihomo payload is empty")
+ return digest.hexdigest()
+
+
+def _https_response(response) -> None:
+ if urllib.parse.urlsplit(response.geturl()).scheme != "https":
+ raise RuntimeError("official mihomo download redirected outside HTTPS")
+
+
+def latest_release() -> str:
+ """Read the official latest/version.txt asset only to form download filenames."""
+ request = urllib.request.Request(
+ LATEST_VERSION_URL, headers={"User-Agent": "VCore-interop-scripts"}
+ )
+ try:
+ with urllib.request.urlopen(request, timeout=30) as response:
+ _https_response(response)
+ contents = io.BytesIO()
+ _copy_and_hash(response, contents, MAX_VERSION_BYTES)
+ tag = contents.getvalue().decode("utf-8").strip()
+ except (OSError, ValueError, http.client.HTTPException) as error:
+ raise RuntimeError(
+ f"cannot read official mihomo latest version.txt: {error}"
+ ) from error
+ return _release_tag(tag)
+
+
+def _asset(tag: str, target: str) -> tuple[str, str]:
+ variant = "-v1" if target in {"linux-amd64", "windows-amd64"} else ""
+ suffix = "zip" if target.startswith("windows-") else "gz"
+ name = f"mihomo-{target}{variant}-{tag}.{suffix}"
+ return name, f"{RELEASE_URL}/{tag}/{name}"
+
+
+@contextmanager
+def _payload(archive: Path):
+ if archive.suffix == ".gz":
+ with gzip.open(archive, "rb") as payload:
+ yield payload
+ return
+ with zipfile.ZipFile(archive) as bundle:
+ files = []
+ for member in bundle.infolist():
+ name = member.filename
+ if (
+ PurePosixPath(name).is_absolute()
+ or ".." in PurePosixPath(name).parts
+ or "\\" in name
+ or ":" in name
+ ):
+ raise RuntimeError("unsafe path in official mihomo ZIP")
+ if member.is_dir():
+ continue
+ mode = stat.S_IFMT(member.external_attr >> 16)
+ if (
+ mode not in {0, stat.S_IFREG}
+ or member.flag_bits & 1
+ or len(PurePosixPath(name).parts) != 1
+ or not name.endswith(".exe")
+ ):
+ raise RuntimeError("unsafe executable entry in official mihomo ZIP")
+ files.append(member)
+ if len(files) != 1:
+ raise RuntimeError(
+ "official mihomo ZIP must contain exactly one executable"
+ )
+ if not 0 < files[0].file_size <= MAX_BINARY_BYTES:
+ raise RuntimeError("official mihomo executable exceeds its size limit")
+ with bundle.open(files[0]) as payload:
+ yield payload
+
+
+def _report(
+ tag: str, asset: str, url: str, archive_digest: str, digest: str, binary: Path
+):
+ print(f"Mihomo download release tag: {tag}", flush=True)
+ print(f"Official mihomo asset: {asset}", flush=True)
+ print(f"Official mihomo download URL: {url}", flush=True)
+ print(f"Mihomo archive SHA-256 (downloaded content): {archive_digest}", flush=True)
+ print(f"Mihomo binary SHA-256 (downloaded content): {digest}", flush=True)
+ print(f"Official mihomo binary: {binary}", flush=True)
+
+
+def download_mihomo(
+ target: str | None = None,
+ *,
+ release: str | None = None,
+ directory: Path | None = None,
+ identity: dict | None = None,
+) -> Path:
+ """Download a fresh official archive and atomically publish its binary.
+
+ Callers can share a freshly read version.txt tag for multiple architectures.
+ Every call downloads again; failures neither replace nor return an old binary.
+ Hashes identify downloaded content, without claiming an upstream digest check.
+ The harness records the actual version by running the binary with -v.
+ """
+ target = _target(target)
+ if release is None:
+ release = latest_release()
+ tag = _release_tag(release)
+ name, url = _asset(tag, target)
+ directory = (
+ directory
+ if directory is not None
+ else CORE_DIR / "target/interop/mihomo" / tag / target
+ )
+ binary = directory / ("mihomo.exe" if target.startswith("windows-") else "mihomo")
+ request = urllib.request.Request(
+ url, headers={"User-Agent": "VCore-interop-scripts"}
+ )
+ try:
+ directory.mkdir(parents=True, exist_ok=True)
+ with tempfile.TemporaryDirectory(prefix=".download-", dir=directory) as staging:
+ staged_archive = Path(staging) / name
+ staged_binary = Path(staging) / binary.name
+ with (
+ urllib.request.urlopen(request, timeout=30) as response,
+ staged_archive.open("wb") as output,
+ ):
+ _https_response(response)
+ archive_digest = _copy_and_hash(response, output, MAX_ARCHIVE_BYTES)
+ with _payload(staged_archive) as source, staged_binary.open("wb") as output:
+ digest = _copy_and_hash(source, output, MAX_BINARY_BYTES)
+ staged_binary.chmod(0o755)
+ os.replace(staged_binary, binary)
+ except (
+ OSError,
+ EOFError,
+ http.client.HTTPException,
+ zipfile.BadZipFile,
+ zlib.error,
+ ) as error:
+ raise RuntimeError(f"cannot download official mihomo {tag}: {error}") from error
+ _report(tag, name, url, archive_digest, digest, binary)
+ if identity is not None:
+ identity.update(
+ kind="M",
+ target=target,
+ release=tag,
+ asset=name,
+ source_url=url,
+ archive_sha256=archive_digest,
+ binary_sha256=digest,
+ )
+ return binary
diff --git a/scripts/src/vcore_scripts/native_release.py b/scripts/src/vcore_scripts/native_release.py
new file mode 100644
index 0000000..a2b5852
--- /dev/null
+++ b/scripts/src/vcore_scripts/native_release.py
@@ -0,0 +1,229 @@
+"""Fresh official native peers. No API lookup, source build or stale fallback."""
+
+from __future__ import annotations
+
+import http.client
+import os
+import platform
+import re
+import stat
+import subprocess
+import tarfile
+import tempfile
+import urllib.request
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+
+from .mihomo_release import (
+ MAX_ARCHIVE_BYTES,
+ MAX_BINARY_BYTES,
+ _copy_and_hash,
+ _https_response,
+)
+from .protocol_peers import run_command
+
+
+@dataclass(frozen=True)
+class PeerArtifact:
+ binary: Path
+ identity: dict
+
+
+def download_native(
+ kind: str,
+ directory: Path,
+ target: str | None = None,
+ *,
+ defer_version: bool = False,
+) -> PeerArtifact:
+ try:
+ return _download_native(kind, directory, target, defer_version)
+ except (
+ OSError,
+ ValueError,
+ zipfile.BadZipFile,
+ tarfile.TarError,
+ http.client.HTTPException,
+ subprocess.SubprocessError,
+ ):
+ raise RuntimeError(
+ "official native peer download or version check failed"
+ ) from None
+
+
+def _download_native(
+ kind: str, directory: Path, target: str | None, defer_version: bool
+) -> PeerArtifact:
+ """Install only a named executable into this run's owned directory."""
+ if target is None:
+ architecture = {"aarch64": "arm64", "x86_64": "amd64"}.get(
+ platform.machine().lower(), platform.machine().lower()
+ )
+ target = f"{platform.system().lower()}-{architecture}"
+ assets = {
+ "SS": (
+ "shadowsocks/shadowsocks-rust",
+ "ssserver",
+ {"linux-arm64": "aarch64-unknown-linux-musl"},
+ ),
+ "V2": (
+ "v2fly/v2ray-core",
+ "v2ray",
+ {
+ "darwin-arm64": "v2ray-macos-arm64-v8a.zip",
+ "darwin-amd64": "v2ray-macos-64.zip",
+ "linux-arm64": "v2ray-linux-arm64-v8a.zip",
+ "linux-amd64": "v2ray-linux-64.zip",
+ },
+ ),
+ "XR": (
+ "XTLS/Xray-core",
+ "xray",
+ {
+ "darwin-arm64": "Xray-macos-arm64-v8a.zip",
+ "darwin-amd64": "Xray-macos-64.zip",
+ "linux-arm64": "Xray-linux-arm64-v8a.zip",
+ "linux-amd64": "Xray-linux-64.zip",
+ },
+ ),
+ "H": (
+ "HyNetworks/hysteria",
+ "hysteria",
+ {
+ target: f"hysteria-{target}"
+ for target in [
+ "darwin-arm64",
+ "darwin-amd64",
+ "linux-arm64",
+ "linux-amd64",
+ ]
+ },
+ ),
+ }
+ if kind not in assets or target not in assets[kind][2]:
+ raise RuntimeError("unsupported official native peer target")
+ project, name, targets = assets[kind]
+ asset = targets[target]
+ if kind == "SS":
+ # SS assets include their tag; follow latest's HTTP redirect, not an API
+ # or a pinned version. The executable reports its own actual version.
+ request = urllib.request.Request(
+ f"https://github.com/{project}/releases/latest",
+ method="HEAD",
+ headers={"User-Agent": "VCore-interop-scripts"},
+ )
+ with urllib.request.urlopen(request, timeout=30) as response:
+ prefix = f"https://github.com/{project}/releases/tag/"
+ resolved = response.geturl()
+ if not resolved.startswith(prefix) or not re.fullmatch(
+ r"v\d+\.\d+\.\d+", resolved[len(prefix) :]
+ ):
+ raise RuntimeError("invalid official SS latest stable redirect")
+ tag = resolved[len(prefix) :]
+ asset = f"shadowsocks-{tag}.{asset}.tar.xz"
+ url = f"https://github.com/{project}/releases/latest/download/{asset}"
+ directory.mkdir(parents=True, exist_ok=True)
+ binary = directory / name
+ with tempfile.TemporaryDirectory(prefix=".download-", dir=directory) as temporary:
+ archive, executable = Path(temporary) / "archive.zip", Path(temporary) / name
+ request = urllib.request.Request(
+ url, headers={"User-Agent": "VCore-interop-scripts"}
+ )
+ with (
+ urllib.request.urlopen(request, timeout=30) as response,
+ archive.open("wb") as output,
+ ):
+ _https_response(response)
+ archive_hash = _copy_and_hash(response, output, MAX_ARCHIVE_BYTES)
+ if kind == "H":
+ with archive.open("rb") as source, executable.open("wb") as output:
+ binary_hash = _copy_and_hash(source, output, MAX_BINARY_BYTES)
+ elif kind == "SS":
+ binary_hash = _extract_tar(archive, executable, name)
+ else:
+ binary_hash = _extract_zip(archive, executable, name)
+ executable.chmod(0o755)
+ # Foreign executables are verified inside the owned VM before traffic;
+ # a deferred artifact is not yet a ready/verified peer.
+ version = None
+ if not defer_version:
+ result = run_command(
+ [str(executable), "--version" if kind == "SS" else "version"],
+ timeout=10,
+ limit=4096,
+ )
+ if result.returncode != 0 or not result.cleanup:
+ raise RuntimeError("official native peer version check failed")
+ version = result.stdout.decode("utf-8", errors="replace").strip()
+ if not version:
+ raise RuntimeError("invalid official native peer version output")
+ os.replace(executable, binary)
+ return PeerArtifact(
+ binary,
+ {
+ "kind": kind,
+ "target": target,
+ "source_url": url,
+ "archive_sha256": archive_hash,
+ "binary_sha256": binary_hash,
+ "version": version,
+ },
+ )
+
+
+def _extract_zip(archive: Path, executable: Path, name: str) -> str:
+ with zipfile.ZipFile(archive) as bundle:
+ matches = []
+ for member in bundle.infolist():
+ path = PurePosixPath(member.filename)
+ mode = stat.S_IFMT(member.external_attr >> 16)
+ if (
+ path.is_absolute()
+ or ".." in path.parts
+ or "\\" in member.filename
+ or ":" in member.filename
+ or mode not in {0, stat.S_IFREG, stat.S_IFDIR}
+ or member.flag_bits & 1
+ ):
+ raise RuntimeError("unsafe official native peer archive")
+ if member.filename == name:
+ matches.append(member)
+ if len(matches) != 1 or not 0 < matches[0].file_size <= MAX_BINARY_BYTES:
+ raise RuntimeError("invalid official native peer executable")
+ with bundle.open(matches[0]) as source, executable.open("wb") as output:
+ binary_hash = _copy_and_hash(source, output, MAX_BINARY_BYTES)
+ return binary_hash
+
+
+def _extract_tar(archive: Path, executable: Path, name: str) -> str:
+ """Stream a bounded official bundle; never extract archive paths or links."""
+ found, total, digest = 0, 0, None
+ with tarfile.open(archive, "r|xz") as bundle:
+ for index, entry in enumerate(bundle):
+ path = PurePosixPath(entry.name)
+ total += entry.size
+ if (
+ index >= 32
+ or total > MAX_BINARY_BYTES
+ or path.is_absolute()
+ or ".." in path.parts
+ or "\\" in entry.name
+ or ":" in entry.name
+ or not (entry.isfile() or entry.isdir())
+ ):
+ raise RuntimeError("unsafe official native peer archive")
+ if entry.name != name:
+ continue
+ found += 1
+ if (
+ found != 1
+ or not entry.isfile()
+ or not 0 < entry.size <= MAX_BINARY_BYTES
+ ):
+ raise RuntimeError("invalid official native peer executable")
+ with bundle.extractfile(entry) as source, executable.open("wb") as output:
+ digest = _copy_and_hash(source, output, MAX_BINARY_BYTES)
+ if found != 1:
+ raise RuntimeError("missing official native peer executable")
+ return digest
diff --git a/scripts/src/vcore_scripts/platform_delivery.py b/scripts/src/vcore_scripts/platform_delivery.py
new file mode 100644
index 0000000..5df4fc0
--- /dev/null
+++ b/scripts/src/vcore_scripts/platform_delivery.py
@@ -0,0 +1,495 @@
+"""Production build evidence. This is not device or signed-release acceptance."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import platform
+import plistlib
+import shutil
+import stat
+import subprocess
+from datetime import UTC, datetime
+from pathlib import Path, PurePosixPath
+
+from . import builds
+
+GROUPS = {"apple", "android", "windows-arm64", "windows-x64"}
+APPLE_LIBRARIES = {
+ "ios-arm64": ("ios", None, {"arm64"}),
+ "ios-arm64_x86_64-simulator": ("ios", "simulator", {"arm64", "x86_64"}),
+ "macos-arm64_x86_64": ("macos", None, {"arm64", "x86_64"}),
+}
+
+
+def _sha(path: Path) -> str:
+ with path.open("rb") as stream:
+ return hashlib.file_digest(stream, "sha256").hexdigest()
+
+
+def _output(argv: list[str], root: Path) -> str:
+ return subprocess.check_output(argv, cwd=root, text=True, timeout=60).strip()
+
+
+def _source(root: Path) -> dict:
+ if _output(["git", "status", "--porcelain", "--untracked-files=normal"], root):
+ raise ValueError("delivery requires a clean committed source checkout")
+ return {
+ "commit": _output(["git", "rev-parse", "HEAD"], root),
+ "tree": _output(["git", "rev-parse", "HEAD^{tree}"], root),
+ "lockSha256": _sha(root / "Cargo.lock"),
+ }
+
+
+def check_delivery(
+ manifests: list[Path], *, source_dir: Path | None = None, complete: bool = False
+) -> None:
+ source = _source(source_dir or builds.CORE_DIR)
+ groups = set()
+ if not manifests:
+ raise ValueError("empty manifest set cannot pass")
+ for manifest in manifests:
+ record = json.loads(manifest.read_text(encoding="utf-8"))
+ if (
+ record.get("formatVersion") != 1
+ or record.get("profile") != "release"
+ or record.get("features") != builds.DEFAULT_FEATURES.split(",")
+ or record.get("buildIdentity") != builds.EXPECTED_IDENTITY.decode()
+ ):
+ raise ValueError("incompatible production artifact metadata")
+ if record.get("source") != source:
+ raise ValueError("artifact source/lock identity does not match checkout")
+ group = record.get("group")
+ if group not in GROUPS or group in groups:
+ raise ValueError("duplicate delivery group")
+ groups.add(group)
+ toolchain = record.get("toolchain", {})
+ required = {"rustc", "cargo"} | (
+ {"ndk", "clang", "androidApi"}
+ if group == "android"
+ else {"xcode", "iphoneos", "iphonesimulator", "macosx"}
+ if group == "apple"
+ else {"msvc", "windowsSdk"}
+ )
+ if not all(
+ isinstance(toolchain.get(key), str) and toolchain[key] for key in required
+ ):
+ raise ValueError("missing toolchain evidence")
+ rows = record.get("artifacts", [])
+ if not rows:
+ raise ValueError("empty artifact set cannot pass")
+ names = set()
+ for row in rows:
+ name = row["path"]
+ relative = PurePosixPath(name)
+ if (
+ relative.is_absolute()
+ or ".." in relative.parts
+ or "\\" in name
+ or str(relative) != name
+ or name in names
+ ):
+ raise ValueError("invalid or duplicate artifact path")
+ names.add(name)
+ base = manifest.parent.resolve()
+ path = base / name
+ if not path.is_file() or any(
+ base.joinpath(*relative.parts[:index]).is_symlink()
+ for index in range(1, len(relative.parts) + 1)
+ ):
+ raise ValueError(f"missing or non-regular artifact: {name}")
+ if path.stat().st_size != row["size"] or _sha(path) != row["sha256"]:
+ raise ValueError(f"artifact hash/size mismatch: {name}")
+ actual = {
+ p.relative_to(manifest.parent).as_posix()
+ for p in manifest.parent.rglob("*")
+ if p.is_file() and p != manifest
+ }
+ if actual != names:
+ raise ValueError("unrecorded or missing artifact files")
+ if record.get("group") == "android":
+ expected = {
+ f"{abi}/{name}"
+ for abi in ("arm64-v8a", "x86_64")
+ for name in ("libvcore.so", "libc++_shared.so")
+ }
+ if names != expected:
+ raise ValueError("Android delivery requires both ABIs and C++ runtimes")
+ for abi, machine in (("arm64-v8a", 183), ("x86_64", 62)):
+ for name in ("libvcore.so", "libc++_shared.so"):
+ path = manifest.parent / abi / name
+ with path.open("rb") as stream:
+ header = stream.read(20)
+ if (
+ header[:7] != b"\x7fELF\x02\x01\x01"
+ or len(header) != 20
+ or int.from_bytes(header[16:18], "little") != 3
+ or int.from_bytes(header[18:20], "little") != machine
+ ):
+ raise ValueError(
+ f"wrong Android ELF architecture: {abi}/{name}"
+ )
+ if name == "libvcore.so":
+ builds._require_identity(path, "Android")
+ elif group == "apple":
+ expected = {"LibVCore.xcframework/Info.plist"} | {
+ f"LibVCore.xcframework/{identifier}/{name}"
+ for identifier in APPLE_LIBRARIES
+ for name in (
+ "libvcore.a",
+ "Headers/vcore.h",
+ "Headers/module.modulemap",
+ )
+ }
+ if names != expected:
+ raise ValueError("incomplete Apple XCFramework")
+ with (manifest.parent / "LibVCore.xcframework/Info.plist").open(
+ "rb"
+ ) as stream:
+ libraries = plistlib.load(stream).get("AvailableLibraries", [])
+ if len(libraries) != 3:
+ raise ValueError("incomplete Apple platform slices")
+ identifiers = set()
+ for library in libraries:
+ identifier = library.get("LibraryIdentifier")
+ if identifier not in APPLE_LIBRARIES or identifier in identifiers:
+ raise ValueError("invalid Apple library identifier")
+ identifiers.add(identifier)
+ target_os, variant, architectures = APPLE_LIBRARIES[identifier]
+ if (
+ library.get("SupportedPlatform") != target_os
+ or library.get("SupportedPlatformVariant") != variant
+ or set(library.get("SupportedArchitectures", [])) != architectures
+ or library.get("LibraryPath") != "libvcore.a"
+ or library.get("HeadersPath") != "Headers"
+ ):
+ raise ValueError("invalid Apple slice metadata")
+ path = (
+ manifest.parent / "LibVCore.xcframework" / identifier / "libvcore.a"
+ )
+ actual_archs = set(
+ _output(
+ ["xcrun", "lipo", "-archs", str(path)], builds.CORE_DIR
+ ).split()
+ )
+ if actual_archs != architectures:
+ raise ValueError("wrong Apple binary architecture")
+ builds._require_identity(path, "Apple")
+ else:
+ arch = group.removeprefix("windows-")
+ expected = {
+ "vcore.dll",
+ "vcore-windows-vpn-host.exe",
+ "vcore-windows-session-host.exe",
+ }
+ if names != expected | {"vcore-windows-artifacts.json"}:
+ raise ValueError("incomplete Windows artifact set")
+ if (
+ record.get("host", {}).get("os") != "Windows"
+ or record["host"].get("architecture") != arch
+ ):
+ raise ValueError(
+ "Windows delivery requires native OS architecture evidence"
+ )
+ for name in expected:
+ builds._require_windows_architecture(manifest.parent / name, arch)
+ builds._require_identity(manifest.parent / "vcore.dll", "Windows")
+ package = json.loads(
+ (manifest.parent / "vcore-windows-artifacts.json").read_text()
+ )
+ if (
+ package.get("formatVersion") != 1
+ or package.get("architecture") != arch
+ or package.get("windowsPackageIntegrationRevision") != 3
+ or package.get("buildIdentity") != record["buildIdentity"]
+ or package.get("artifacts")
+ != {
+ row["path"]: row["sha256"]
+ for row in rows
+ if row["path"] in expected
+ }
+ ):
+ raise ValueError("Windows package integration identity mismatch")
+ print(
+ f"PASS {record['group']} artifact integrity (not device/release acceptance)"
+ )
+ if complete and groups != GROUPS:
+ raise ValueError(
+ "complete platform artifacts require Apple, Android, "
+ "native Windows ARM64 and x64"
+ )
+ if complete:
+ print(
+ "PASS production platform artifacts; "
+ "ABI, devices and release require separate evidence"
+ )
+
+
+def build_delivery(platform_name: str) -> None:
+ if os.environ.get("VCORE_BUILD_PROFILE", "release") != "release":
+ raise ValueError("delivery requires the release profile")
+ if (
+ os.environ.get("VCORE_FEATURES", builds.DEFAULT_FEATURES)
+ != builds.DEFAULT_FEATURES
+ ):
+ raise ValueError("delivery requires the complete production feature set")
+ # Keep the recorded build command honest: existing development builds still
+ # allow customization, but acceptance must not inherit hidden overrides.
+ overrides = [
+ name
+ for name in os.environ
+ if (
+ name
+ in {
+ "RUSTFLAGS",
+ "CARGO_ENCODED_RUSTFLAGS",
+ "CARGO_TARGET_DIR",
+ "VCORE_ANDROID_OUTPUT_DIR",
+ "VCORE_APPLE_DIST_DIR",
+ "VCORE_ANDROID_TARGETS",
+ }
+ or name.startswith("CARGO_PROFILE_")
+ )
+ and os.environ[name]
+ ]
+ if overrides:
+ raise ValueError(
+ "unsupported delivery build overrides: " + ", ".join(sorted(overrides))
+ )
+ source = _source(builds.CORE_DIR)
+ group = platform_name
+ architecture = platform.machine().lower()
+ toolchain = {
+ "rustc": _output(["rustc", "-Vv"], builds.CORE_DIR),
+ "cargo": _output(["cargo", "--version"], builds.CORE_DIR),
+ }
+ if platform_name == "windows":
+ if os.name != "nt":
+ raise ValueError("Windows delivery must run on native Windows")
+ architecture = builds._windows_architecture()
+ group += "-" + architecture
+ environment = builds._windows_msvc_environment(architecture)
+ # Windows env names are case insensitive, even when a subprocess returns
+ # a plain Python dict. Never persist the full environment (credentials).
+ normalized = {key.upper(): value for key, value in environment.items()}
+ toolchain["msvc"] = normalized.get("VCTOOLSVERSION", "").strip()
+ toolchain["windowsSdk"] = normalized.get("WINDOWSSDKVERSION", "").strip("\\ ")
+ toolchain["cmake"] = _output(["cmake", "--version"], builds.CORE_DIR)
+ toolchain["generator"] = "Ninja" if architecture == "arm64" else "Visual Studio"
+ if architecture == "arm64":
+ toolchain["clang"] = _output(
+ [normalized["VCORE_WINDOWS_ARM64_CLANG"], "--version"], builds.CORE_DIR
+ )
+ toolchain["assembly"] = "enabled"
+ elif platform_name == "apple":
+ toolchain["xcode"] = _output(["xcodebuild", "-version"], builds.CORE_DIR)
+ for sdk in ("iphoneos", "iphonesimulator", "macosx"):
+ toolchain[sdk] = _output(
+ ["xcrun", "--sdk", sdk, "--show-sdk-version"], builds.CORE_DIR
+ )
+ toolchain["iosDeploymentTarget"] = os.environ.get(
+ "VCORE_IOS_DEPLOYMENT_TARGET", "13.0"
+ )
+ toolchain["macosDeploymentTarget"] = os.environ.get(
+ "VCORE_MACOS_DEPLOYMENT_TARGET", "10.15"
+ )
+ else:
+ android_home = Path(
+ os.environ.get("ANDROID_HOME", Path.home() / "Library/Android/sdk")
+ )
+ ndk = Path(
+ os.environ.get(
+ "ANDROID_NDK_HOME",
+ android_home
+ / "ndk"
+ / os.environ.get("VCORE_ANDROID_NDK_VERSION", "28.2.13676358"),
+ )
+ )
+ toolchain["ndk"] = (ndk / "source.properties").read_text().strip()
+ toolchain["clang"] = _output(
+ [str(builds._android_toolchain(ndk) / "bin/clang"), "--version"],
+ builds.CORE_DIR,
+ )
+ toolchain["androidApi"] = os.environ.get("VCORE_ANDROID_API", "24")
+ output = builds.CORE_DIR / "dist" / platform_name
+ if platform_name == "windows":
+ output /= architecture
+ # Check the lexical path before resolving, unlinking a manifest, or letting
+ # a builder clean output. CORE_DIR is the canonical, trusted checkout root;
+ # Windows junctions and other reparse points can redirect descendants too.
+ current = builds.CORE_DIR
+ for part in output.relative_to(builds.CORE_DIR).parts:
+ current /= part
+ try:
+ metadata = current.lstat()
+ except FileNotFoundError:
+ break
+ if stat.S_ISLNK(metadata.st_mode) or (
+ getattr(metadata, "st_file_attributes", 0)
+ & stat.FILE_ATTRIBUTE_REPARSE_POINT
+ ):
+ raise ValueError(
+ "delivery output must not contain symlinks or reparse points"
+ )
+ manifest = output / "vcore-delivery.json"
+ if platform_name == "android":
+ # Development builds can leave additional ABIs in the same ignored
+ # directory. Never mix those artifacts into a fresh delivery manifest.
+ if output.exists():
+ shutil.rmtree(output)
+ else:
+ manifest.unlink(missing_ok=True)
+ started = datetime.now(UTC).isoformat()
+ {
+ "apple": builds.build_apple,
+ "android": builds.build_android,
+ "windows": builds.build_windows,
+ }[platform_name]()
+ if _source(builds.CORE_DIR) != source:
+ raise ValueError("source changed during delivery build")
+ record = {
+ "formatVersion": 1,
+ "group": group,
+ "profile": "release",
+ "source": source,
+ "features": builds.DEFAULT_FEATURES.split(","),
+ "buildIdentity": builds.EXPECTED_IDENTITY.decode(),
+ "host": {
+ "os": platform.system(),
+ "architecture": architecture,
+ "osVersion": platform.release(),
+ },
+ "toolchain": toolchain,
+ "startedUtc": started,
+ "finishedUtc": datetime.now(UTC).isoformat(),
+ "artifacts": [
+ {
+ "path": path.relative_to(output).as_posix(),
+ "size": path.stat().st_size,
+ "sha256": _sha(path),
+ }
+ for path in sorted(output.rglob("*"))
+ if path.is_file()
+ ],
+ }
+ manifest.write_text(
+ json.dumps(record, indent=2, sort_keys=True) + "\n", encoding="utf-8"
+ )
+ try:
+ check_delivery([manifest])
+ except Exception:
+ manifest.unlink(missing_ok=True)
+ raise
+ print(manifest)
+
+
+def check_abi(manifest: Path) -> None:
+ """Compile a real C consumer; no replacement library and no protocol servers."""
+ # Commands below run from an isolated output directory, not the caller cwd.
+ manifest = manifest.resolve()
+ check_delivery([manifest])
+ record = json.loads(manifest.read_text(encoding="utf-8"))
+ group = record["group"]
+ root = builds.CORE_DIR
+ work = root / "target/platform-delivery/abi" / group
+ work.mkdir(parents=True, exist_ok=True)
+ (work / "result.json").unlink(missing_ok=True)
+ source = root / "scripts/fixtures/platform_abi.c"
+ binary = work / ("abi.exe" if os.name == "nt" else "abi")
+ environment = os.environ.copy()
+ if group == "apple" and platform.system() == "Darwin":
+ library = manifest.parent / "LibVCore.xcframework/macos-arm64_x86_64/libvcore.a"
+ command = [
+ "xcrun",
+ "clang",
+ "-Wall",
+ "-Wextra",
+ "-Werror",
+ "-I",
+ str(root / "include"),
+ str(source),
+ str(library),
+ "-lc++",
+ "-lresolv",
+ "-framework",
+ "Security",
+ "-framework",
+ "SystemConfiguration",
+ "-framework",
+ "CoreFoundation",
+ "-o",
+ str(binary),
+ ]
+ execute = [str(binary)]
+ architecture = platform.machine()
+ elif group.startswith("windows-") and os.name == "nt":
+ architecture = builds._windows_architecture()
+ if group != "windows-" + architecture:
+ raise ValueError("ABI check cannot substitute emulation for native Windows")
+ environment = builds._windows_msvc_environment(architecture)
+ search_path = next(
+ value for key, value in environment.items() if key.upper() == "PATH"
+ )
+ # CreateProcess does not use env[PATH] to resolve the executable. Resolve
+ # cl from vcvars explicitly rather than requiring it in the parent PATH.
+ compiler = shutil.which("cl", path=search_path)
+ if not compiler:
+ raise ValueError(
+ "MSVC C compiler is unavailable in the selected environment"
+ )
+ command = [
+ compiler,
+ "/nologo",
+ "/std:c11",
+ "/W4",
+ "/WX",
+ "/MT",
+ "/I" + str(root / "include"),
+ str(source),
+ "/Fe:" + str(binary),
+ "/Fo:" + str(work / "abi.obj"),
+ ]
+ execute = [str(binary), str(manifest.parent / "vcore.dll")]
+ else:
+ raise ValueError(
+ "native ABI runner requires a matching macOS or Windows artifact"
+ )
+ subprocess.run(command, cwd=work, env=environment, check=True, timeout=120)
+ subprocess.run(execute, cwd=work, env=environment, check=True, timeout=60)
+ if group.startswith("windows-"):
+ target = {"arm64": "aarch64-pc-windows-msvc", "x64": "x86_64-pc-windows-msvc"}[
+ architecture
+ ]
+ base = [
+ "cargo",
+ "test",
+ "--locked",
+ "--release",
+ "--target",
+ target,
+ "--features",
+ "ffi",
+ ]
+ for suffix in (
+ ["--lib", "windows::snapshot::tests"],
+ ["--test", "windows_session_startup"],
+ ):
+ subprocess.run(
+ base + suffix, cwd=root, env=environment, check=True, timeout=1200
+ )
+ if _source(root) != record["source"]:
+ raise ValueError("source changed during ABI check")
+ evidence = {
+ "kind": "native-production-abi",
+ "group": group,
+ "source": record["source"],
+ "manifestSha256": _sha(manifest),
+ "architecture": architecture,
+ "iterations": 1000,
+ "invalidApiRejected": True,
+ "finishedUtc": datetime.now(UTC).isoformat(),
+ }
+ (work / "result.json").write_text(
+ json.dumps(evidence, indent=2) + "\n", encoding="utf-8"
+ )
diff --git a/scripts/src/vcore_scripts/protocol_catalogs.py b/scripts/src/vcore_scripts/protocol_catalogs.py
new file mode 100644
index 0000000..fa73c08
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_catalogs.py
@@ -0,0 +1,84 @@
+"""Executable catalog integrity; production fields are documented in config.yaml."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+CATALOG_DIR = Path(__file__).resolve().parents[3] / "tests" / "protocols"
+PROTOCOLS = {"trojan", "vmess", "vless", "hysteria2"}
+PEERS = {"M", "H", "XR", "V2"}
+SUITES = {
+ "FOUNDATIONS": (
+ "schema",
+ "security",
+ "streams",
+ "datagrams",
+ "features",
+ "regression",
+ ),
+ "TROJAN": ("codec", "configuration", "cancellation", "acceptance"),
+ "VMESS": ("identity", "codec", "udp", "close", "acceptance"),
+ "VLESS": ("tcp", "transports", "vision", "acceptance"),
+ "XHTTP": ("requests", "download", "mux", "http3", "acceptance"),
+ "HYSTERIA2": ("tcp", "udp", "bandwidth", "salamander", "hopping", "acceptance"),
+ "SECURITY": ("encryption", "reality", "ech", "jls", "acceptance"),
+ "INTEGRATION": ("routing", "lifecycle", "pressure", "regression"),
+}
+CATEGORIES = {
+ f"{suite}.{category}"
+ for suite, categories in SUITES.items()
+ for category in categories
+}
+# Stable evidence tags; field semantics live in docs/config.yaml, not a planning mirror.
+FIELD_IDS = {
+ f"{prefix}{index:02}"
+ for prefix, count in {
+ "C": 6,
+ "T": 8,
+ "W": 7,
+ "G": 6,
+ "H": 6,
+ "TR": 2,
+ "VM": 8,
+ "VL": 6,
+ "X": 29,
+ "D": 32,
+ "S": 13,
+ "M": 7,
+ "HY": 8,
+ }.items()
+ for index in range(1, count + 1)
+ if not (
+ (prefix == "D" and 19 <= index <= 24) or (prefix == "S" and 6 <= index <= 11)
+ )
+}
+
+
+def _unique_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+ result: dict[str, Any] = {}
+ for key, value in pairs:
+ if key in result:
+ raise ValueError("protocol catalog: duplicate JSON key")
+ result[key] = value
+ return result
+
+
+def check_protocol_catalogs(directory: Path = CATALOG_DIR) -> None:
+ from .protocol_evidence import check_limit_references, load_manifest
+
+ cases = load_manifest()
+ check_limit_references(cases, directory / "limits.json")
+ print(
+ json.dumps(
+ {
+ "kind": "executable-catalog-check",
+ "status": "VALID",
+ "behavior_status": "NOT RUN",
+ "cases": len(cases),
+ "fields": len(set().union(*(set(case["row_ids"]) for case in cases))),
+ },
+ sort_keys=True,
+ )
+ )
diff --git a/scripts/src/vcore_scripts/protocol_containers.py b/scripts/src/vcore_scripts/protocol_containers.py
new file mode 100644
index 0000000..97d21e6
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_containers.py
@@ -0,0 +1,234 @@
+"""Owned Apple Container test peers; no native-server fallback or host publishing."""
+
+from __future__ import annotations
+
+import hashlib
+import ipaddress
+import json
+import re
+import socket
+import time
+import uuid
+from contextlib import contextmanager
+from contextvars import ContextVar
+from pathlib import Path
+
+from .protocol_inputs import redact
+from .protocol_peers import OwnedProcess, run_command
+
+NETWORK = "vcore-mihomo-interop"
+IMAGE = "docker.io/library/python:3-alpine"
+_FROZEN_IMAGE = ContextVar("vcore_frozen_container_image", default=None)
+
+
+def _pull_image(log=None):
+ argv = ["container", "image", "pull", IMAGE]
+ result = run_command(argv, timeout=180)
+ if log is not None:
+ log.write_text(redact(result.stdout.decode(errors="replace")))
+ if result.returncode != 0 or not result.cleanup:
+ raise RuntimeError("isolated container image pull failed")
+ inspection = json.loads(command("image", "inspect", IMAGE))[0]
+ digest = inspection["configuration"]["descriptor"]["digest"]
+ if not isinstance(digest, str) or not re.fullmatch(r"sha256:[0-9a-f]{64}", digest):
+ raise RuntimeError("invalid isolated container image identity")
+ return dict(
+ tag=IMAGE,
+ digest=digest,
+ command=argv,
+ exit_code=0,
+ cleanup=True,
+ log=log.name if log is not None else None,
+ )
+
+
+@contextmanager
+def frozen_image(log):
+ """Refresh once per owned run, never a persistent/offline fallback cache."""
+ if _FROZEN_IMAGE.get() is not None:
+ raise RuntimeError("container image scope is already frozen")
+ snapshot = _pull_image(log)
+ token = _FROZEN_IMAGE.set(snapshot["digest"])
+ try:
+ yield snapshot
+ finally:
+ _FROZEN_IMAGE.reset(token)
+
+
+def command(*args, timeout=30):
+ result = run_command(["container", *args], timeout=timeout)
+ if result.returncode != 0 or not result.cleanup:
+ # CLI output may contain fixture paths/config; retain a bounded operation only.
+ raise RuntimeError(f"isolated container operation failed: {args[0]}")
+ return result.stdout.decode(errors="replace")
+
+
+def listing():
+ return json.loads(command("list", "--all", "--format", "json"))
+
+
+class ContainerLab:
+ def __init__(self, record, *, mtu=1280):
+ if type(mtu) is not int or mtu not in (1280, 1500):
+ raise ValueError("unsupported isolated guest MTU")
+ self.mtu = mtu
+ self.record = record
+ self.run_id = uuid.uuid4().hex[:12]
+ network = json.loads(command("network", "inspect", NETWORK))[0]
+ config = network["configuration"]
+ if (
+ config["mode"] != "hostOnly"
+ or config.get("labels", {}).get("purpose") != NETWORK
+ ):
+ raise RuntimeError("owned host-only container network required")
+ self.v4 = ipaddress.ip_network(network["status"]["ipv4Subnet"])
+ self.v6 = ipaddress.ip_network(network["status"]["ipv6Subnet"])
+ digest = _FROZEN_IMAGE.get()
+ if digest is None:
+ digest = _pull_image()["digest"]
+ self.image = IMAGE.split(":")[0] + "@" + digest
+ record.update(
+ backend="Apple Container",
+ network_mode="hostOnly",
+ image_tag=IMAGE,
+ image_digest=digest,
+ run_id=self.run_id,
+ peers=[],
+ host_servers=False,
+ guest_mtu=mtu,
+ )
+
+ def start(self, stack, root: Path, role, argv, *, net_admin=False):
+ peer = ContainerPeer(self, root, role)
+ self.record["peers"].append(peer.record)
+ # Register before launching: CLI interruption/timeout can leave a live VM.
+ stack.callback(peer.stop)
+ peer.start(argv, net_admin=net_admin)
+ return peer
+
+
+class ContainerPeer:
+ def __init__(self, lab, root, role):
+ self.lab, self.root = lab, root
+ self.name = f"vcore-interop-{lab.run_id}-{role}"
+ if len(self.name) > 63:
+ digest = hashlib.sha256(self.name.encode()).hexdigest()[:8]
+ self.name = self.name[:54] + "-" + digest
+ self.record = dict(role=role, name=self.name, joined=False, started=False)
+ self.capture = None
+ self.log = root / "peer.log"
+
+ def start(self, argv, *, net_admin=False):
+ if type(net_admin) is not bool:
+ raise ValueError("isolated capability choice must be boolean")
+ self.record["net_admin"] = net_admin
+ command(
+ "run",
+ "--detach",
+ "--name",
+ self.name,
+ "--label",
+ f"purpose={NETWORK}",
+ "--label",
+ f"vcore-run={self.lab.run_id}",
+ "--network",
+ f"{NETWORK},mtu={self.lab.mtu}",
+ "--cpus",
+ "1",
+ "--memory",
+ "256M",
+ "--arch",
+ "arm64",
+ *(["--cap-add", "CAP_NET_ADMIN"] if net_admin else ["--read-only"]),
+ "--no-dns",
+ "--tmpfs",
+ "/data",
+ "--mount",
+ f"type=bind,source={self.root},target=/data/fixture,readonly",
+ "--entrypoint",
+ "/bin/sh",
+ self.lab.image,
+ "-ec",
+ "for i in $(seq 1 600); do "
+ 'if [ -f /data/fixture/ready ]; then exec "$@"; fi; '
+ "sleep 0.1; done; exit 1",
+ "fixture",
+ *argv,
+ timeout=45,
+ )
+ self.record["started"] = True
+ self.capture = OwnedProcess(
+ ["container", "logs", "--follow", self.name],
+ self.log,
+ {},
+ limit=1024 * 1024,
+ ).__enter__()
+ state = json.loads(command("inspect", self.name))[0]
+ self.record["guest_mtu"] = state["status"]["networks"][0]["mtu"]
+ if self.record["guest_mtu"] != self.lab.mtu:
+ raise RuntimeError("isolated guest MTU differs from requested value")
+ self.ipv4 = state["status"]["networks"][0]["ipv4Address"].split("/")[0]
+ if ipaddress.ip_address(self.ipv4) not in self.lab.v4:
+ raise RuntimeError("container address outside owned network")
+ # Wait for SLAAC/DAD before any business traffic. No host IPv6 binds needed.
+ query = (
+ "import pathlib,json; print(json.dumps(["
+ "[x[0],int(x[4],16)] for line in "
+ "pathlib.Path('/proc/net/if_inet6').read_text().splitlines() "
+ "if (x:=line.split())[5]=='eth0']))"
+ )
+ deadline = time.monotonic() + 15
+ while time.monotonic() < deadline:
+ rows = json.loads(command("exec", self.name, "python", "-c", query))
+ for address, flags in rows:
+ ip = ipaddress.IPv6Address(int(address, 16))
+ if ip in self.lab.v6 and not flags & (0x40 | 0x08):
+ self.ipv6 = str(ip)
+ return
+ time.sleep(0.1)
+ raise RuntimeError("container IPv6 readiness failed")
+
+ def release(self):
+ (self.root / "ready").touch()
+
+ def ensure_alive(self):
+ state = json.loads(command("inspect", self.name))[0]["status"]["state"]
+ if state != "running" or (self.capture and self.capture.overflow.is_set()):
+ raise RuntimeError("owned container peer exited or exceeded output bound")
+
+ def wait_tcp(self, port):
+ deadline = time.monotonic() + 15
+ while time.monotonic() < deadline:
+ self.ensure_alive()
+ try:
+ with socket.create_connection((self.ipv4, port), timeout=0.2):
+ self.record["ready"] = True
+ return
+ except OSError:
+ time.sleep(0.05)
+ raise TimeoutError("container service readiness failed")
+
+ def stop(self):
+ try:
+ owned = next((item for item in listing() if item["id"] == self.name), None)
+ if owned is not None:
+ labels = owned["configuration"].get("labels", {})
+ if (
+ labels.get("purpose") != NETWORK
+ or labels.get("vcore-run") != self.lab.run_id
+ ):
+ raise RuntimeError("container ownership mismatch; refusing cleanup")
+ try:
+ if owned["status"]["state"] == "running":
+ command("stop", "--time", "5", self.name, timeout=15)
+ finally:
+ command("delete", "--force", self.name, timeout=15)
+ finally:
+ if self.capture is not None:
+ self.capture.__exit__(None, None, None)
+ self.record["log_cleanup"] = self.capture.record.get("joined", False)
+ self.record["joined"] = not any(
+ item["id"] == self.name for item in listing()
+ ) and self.record.get("log_cleanup", True)
+ if not self.record["joined"]:
+ raise RuntimeError("owned container cleanup incomplete")
diff --git a/scripts/src/vcore_scripts/protocol_ech.py b/scripts/src/vcore_scripts/protocol_ech.py
new file mode 100644
index 0000000..a984b92
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_ech.py
@@ -0,0 +1,226 @@
+"""SECURITY static ECH consumers against official latest isolated peers."""
+
+from __future__ import annotations
+
+import base64
+import os
+import shutil
+import struct
+import textwrap
+from pathlib import Path
+
+from .protocol_peers import run_command
+
+
+def catalog():
+ cases = {}
+
+ def add(mode, suffix, test):
+ cases[f"SECURITY-ECH-{mode.upper()}-{suffix}"] = ("M", mode, True, test)
+
+ modes = (
+ "tcp-tls",
+ "ws-tls",
+ "upgrade-tls",
+ "upgrade-fast-tls",
+ "grpc-tls",
+ ) + tuple(
+ f"xhttp-{mode}{version}"
+ for mode in (
+ "stream-one",
+ "stream-up",
+ "packet-up",
+ "stream-up-download",
+ "packet-up-download",
+ )
+ for version in ("", "-h1")
+ )
+ for mode in modes:
+ add(mode, "BASE", "public_base")
+ add(mode, "CLOSE", "native_mihomo_close_alignment")
+ for mode in (
+ "tcp-tls",
+ "ws-tls",
+ "grpc-tls",
+ "xhttp-stream-up-download",
+ "xhttp-stream-up-download-h1",
+ ):
+ add(mode, "REJECT", "native_ech_fail_closed")
+ for mode in modes:
+ if "download" in mode:
+ add(mode, "DOWNLOAD", "public_ech_download_identity")
+ for mode in ("tcp-mtls", "ws-mtls", "grpc-mtls"):
+ add(mode, "IDENTITY", "public_tls_identity_and_verification_name")
+ for suffix, test in (
+ ("GRAPH", "runtime::public_graph"),
+ ("ENTRYPOINTS", "runtime::public_entrypoints"),
+ ("IPV6", "runtime::public_ipv6_and_gates"),
+ ("UDP-ISOLATION", "runtime::public_udp_isolation"),
+ ):
+ add("tcp-tls", suffix, test)
+ for mode in ("grpc-tls", "xhttp-stream-up-download"):
+ add(mode, "LIFE", "runtime::public_lifecycle")
+ add(mode, "OWNED", "runtime::owned_resources")
+ return cases
+
+
+def material(directory: Path, key_id: int):
+ """Generate synthetic keys with official OpenSSL, never implement crypto here."""
+ openssl = next(
+ (
+ path
+ for path in (
+ os.environ.get("OPENSSL_BIN"),
+ shutil.which("openssl3"),
+ "/opt/homebrew/opt/openssl@3/bin/openssl",
+ "/usr/local/opt/openssl@3/bin/openssl",
+ shutil.which("openssl"),
+ )
+ if path and Path(path).is_file()
+ ),
+ None,
+ )
+ if openssl is None:
+ raise RuntimeError("OpenSSL with X25519 support is required")
+ private = directory / f"ech-{key_id}.der"
+ generated = run_command(
+ [
+ openssl,
+ "genpkey",
+ "-algorithm",
+ "X25519",
+ "-outform",
+ "DER",
+ "-out",
+ str(private),
+ ],
+ timeout=15,
+ )
+ public = run_command(
+ [
+ openssl,
+ "pkey",
+ "-inform",
+ "DER",
+ "-in",
+ str(private),
+ "-pubout",
+ "-outform",
+ "DER",
+ ],
+ timeout=15,
+ )
+ if any(item.returncode or not item.cleanup for item in (generated, public)):
+ raise RuntimeError("synthetic ECH material generation failed")
+ secret = private.read_bytes()
+ if len(secret) != 48 or len(public.stdout) != 44:
+ raise RuntimeError("unexpected synthetic X25519 DER encoding")
+ name = b"public.invalid"
+ contents = bytes([key_id]) + struct.pack("!HH", 32, 32) + public.stdout[-32:]
+ contents += struct.pack("!HHHBB", 4, 1, 1, 0, len(name)) + name + b"\0\0"
+ config = struct.pack("!HH", 0xFE0D, len(contents)) + contents
+ key_set = (
+ struct.pack("!H", 32) + secret[-32:] + struct.pack("!H", len(config)) + config
+ )
+ return base64.b64encode(struct.pack("!H", len(config)) + config).decode(), key_set
+
+
+def configuration(node, peer, directory, mode, *, kind="M"):
+ primary, first_key = material(directory, 7)
+ download, second_key = material(directory, 9)
+ encoded = base64.b64encode(first_key + second_key).decode()
+ pem = (
+ "-----BEGIN ECH KEYS-----\n"
+ + "\n".join(textwrap.wrap(encoded, 64))
+ + "\n-----END ECH KEYS-----\n"
+ )
+ (directory / "ech-keys.pem").write_text(pem)
+ node["ech-opts"] = dict(enable=True, config=primary)
+ if mode.endswith("-h1"):
+ node["alpn"] = ["http/1.1"]
+ if kind == "M":
+ for listener in peer["listeners"]:
+ listener["ech-key"] = "/data/fixture/ech-keys.pem"
+ elif kind == "XR":
+ for inbound in peer["inbounds"]:
+ inbound["streamSettings"]["tlsSettings"]["echServerKeys"] = encoded
+ else:
+ raise ValueError("unsupported static ECH peer")
+ return dict(ech_download_config=download)
+
+
+def wrong_key(options):
+ wire = bytearray(base64.b64decode(options["config"], validate=True))
+ wire[11:43] = bytes([7]) * 32
+ return dict(enable=True, config=base64.b64encode(wire).decode())
+
+
+def legacy_gateway_command():
+ # Xray's dokodemo-door marks its inbound splice-capable even with TLS.
+ # Its default freedom response path then bypasses the TLS writer. Use
+ # the upstream runtime switch only for this synthetic TLS gateway.
+ return [
+ "env",
+ "XRAY_BUF_SPLICE=disable",
+ "/data/fixture/peer",
+ "run",
+ "-c",
+ "/data/fixture/config.json",
+ ]
+
+
+def legacy_gateway_config(upstream, tls_options):
+ """Official Xray TLS ingress, no custom protocol server or V2Ray patches."""
+ return dict(
+ log={"loglevel": "warning"},
+ inbounds=[
+ dict(
+ listen="::",
+ port=23000,
+ protocol="dokodemo-door",
+ settings=dict(address=upstream, port=23000, network="tcp"),
+ streamSettings=dict(
+ network="tcp", security="tls", tlsSettings=tls_options
+ ),
+ )
+ ],
+ outbounds=[dict(protocol="freedom")],
+ )
+
+
+def field_variants():
+ cases = {}
+ for version in ("h1", "h2", "h3"):
+ for action in ("reject-main", "reject-download", "replace", "clear"):
+ cases[f"{version}-ech-{action}"] = (
+ {
+ "mode": "stream-up",
+ "download-settings": {},
+ "_ech_action": action,
+ "_reject": action.startswith("reject-"),
+ },
+ version,
+ )
+ return cases
+
+
+if __name__ == "__main__":
+ import argparse
+
+ from .mihomo_isolation import exclusive_run
+ from .protocol_vless_container import CLIENT_FINGERPRINTS, run
+
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("output", type=Path)
+ parser.add_argument("cases", nargs="*")
+ parser.add_argument("--client-fingerprint", choices=CLIENT_FINGERPRINTS)
+ args = parser.parse_args()
+ with exclusive_run():
+ raise SystemExit(
+ run(
+ args.output.resolve(),
+ args.cases or None,
+ ech=True,
+ client_fingerprint=args.client_fingerprint,
+ )
+ )
diff --git a/scripts/src/vcore_scripts/protocol_encryption.py b/scripts/src/vcore_scripts/protocol_encryption.py
new file mode 100644
index 0000000..6be795f
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_encryption.py
@@ -0,0 +1,347 @@
+"""Encryption wire checks; not public YAML or complete security acceptance."""
+
+from __future__ import annotations
+
+import base64
+import contextlib
+import json
+import os
+import shutil
+import tempfile
+from pathlib import Path
+
+from .builds import CORE_DIR
+from .mihomo_isolation import exclusive_run
+from .mihomo_release import download_mihomo
+from .protocol_containers import ContainerLab, command
+from .protocol_inputs import redact, same_source, source_identity
+from .protocol_peers import run_command
+
+
+def cases():
+ return {
+ f"{style}-{rtt}-{key}": (style, rtt, key)
+ for style in ("native", "xorpub", "random")
+ for rtt in ("1rtt", "0rtt")
+ for key in ("x25519", "mlkem", "mixed")
+ }
+
+
+def encode(value):
+ return base64.urlsafe_b64encode(bytes.fromhex(value)).decode().rstrip("=")
+
+
+def run(
+ output: Path,
+ selected=None,
+ *,
+ consumer=False,
+ chacha=False,
+ expiry=False,
+ padding="minimal",
+ supplied=None,
+):
+ output = output.resolve()
+ required = cases()
+ if expiry:
+ required = {
+ name: value for name, value in required.items() if value[1] == "0rtt"
+ }
+ paddings = {
+ "minimal": ".100-35-35",
+ "default": "",
+ "fragmented": ".100-35-35.100-1-1.100-47-47",
+ "maximum": ".100-65553-65553",
+ }
+ selected = list(required) if selected is None else selected
+ if (
+ not output.is_relative_to(CORE_DIR / "target/interop/runs")
+ or not selected
+ or len(set(selected)) != len(selected)
+ or not set(selected) <= required.keys()
+ or padding not in paddings
+ or (consumer and (chacha or expiry))
+ ):
+ raise ValueError("fresh run directory and known unique cases required")
+ output.mkdir(parents=True, exist_ok=False)
+ if expiry:
+ test = "native_ticket_expiry"
+ marker = "SECURITY-ENCRYPTION-EXPIRY-PASS full-resumed-expired-full-resumed"
+ elif consumer:
+ test = "public_tcp_roundtrip"
+ marker = (
+ "SECURITY-ENCRYPTION-CONSUMER-PASS rounds=4 bytes_per_direction=10485760"
+ )
+ else:
+ test = "native_encryption_roundtrip"
+ marker = "SECURITY-ENCRYPTION-WIRE-PASS rounds=4 bytes_per_direction=10485760"
+ report = dict(
+ stage="SECURITY.encryption-wire",
+ scope="public-config-and-outbound" if consumer else "native-wire-only",
+ cipher="chacha20-poly1305" if chacha else "cpu-selected",
+ ticket_expiry=expiry,
+ padding=padding,
+ complete_selection=set(selected) == set(required),
+ source=source_identity(),
+ required=list(required),
+ cases=[],
+ isolation={},
+ status="NOT RUN",
+ )
+ try:
+ if supplied is None:
+ identity = {}
+ binary = download_mihomo(
+ "linux-arm64", directory=output / "binaries", identity=identity
+ )
+ else:
+ binary, identity = supplied["M"]
+ report["peer"] = identity
+ built = run_command(
+ [
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ "encryption_wire",
+ "--no-run",
+ ],
+ timeout=240,
+ )
+ (output / "build.log").write_text(redact(built.stdout.decode(errors="replace")))
+ if built.returncode or not built.cleanup:
+ raise RuntimeError("Encryption wire consumer build failed")
+ vectors = json.loads(
+ (CORE_DIR / "tests/protocols/encryption-crypto.json").read_text()
+ )
+ pairs = dict(
+ x25519=(
+ encode(vectors["x25519_public"]),
+ encode(vectors["x25519_private"]),
+ ),
+ mlkem=(encode(vectors["mlkem_public"]), encode(vectors["mlkem_seed"])),
+ )
+ pairs["mixed"] = tuple(
+ ".".join((pairs["x25519"][i], pairs["mlkem"][i], pairs["x25519"][i]))
+ for i in (0, 1)
+ )
+ lab = ContainerLab(report["isolation"], mtu=1500)
+ with (
+ tempfile.TemporaryDirectory(prefix="private-", dir=output) as temporary,
+ contextlib.ExitStack() as stack,
+ ):
+ root = Path(temporary)
+ server_dir, origin_dir = root / "server", root / "origin"
+ server_dir.mkdir()
+ origin_dir.mkdir()
+ shutil.copy2(binary, server_dir / "peer")
+ shutil.copy2(
+ Path(__file__).with_name("container_udp_origin.py"),
+ origin_dir / "origin.py",
+ )
+ origin = lab.start(
+ stack,
+ origin_dir,
+ "security-e-origin",
+ [
+ "env",
+ "VCORE_ISOLATED_ORIGIN=1",
+ "python",
+ "-B",
+ "/data/fixture/origin.py",
+ ],
+ )
+ server = lab.start(
+ stack,
+ server_dir,
+ "security-e-mihomo",
+ [
+ "/data/fixture/peer",
+ "-d",
+ "/data/mihomo",
+ "-f",
+ "/data/fixture/config.json",
+ ],
+ )
+ listeners = []
+ for index, name in enumerate(selected):
+ style, _, key = required[name]
+ lifetime = "2-3s" if expiry else "600s"
+ listeners.append(
+ dict(
+ name=f"encryption-{index}",
+ type="vless",
+ listen="::",
+ port=23000 + index,
+ users=[
+ dict(
+ username="fixture",
+ uuid="07070707-0707-0707-0707-070707070707",
+ )
+ ],
+ decryption=(
+ f"mlkem768x25519plus.{style}.{lifetime}."
+ f"{pairs[key][1]}{paddings[padding]}"
+ ),
+ )
+ )
+ # A distinct native handler has no tickets from the primary.
+ # It exercises genuine unknown-ticket rejection without
+ # patching the peer, restarting it, or replaying business data.
+ listeners.append(
+ {
+ **listeners[-1],
+ "name": f"encryption-fresh-{index}",
+ "port": 23100 + index,
+ }
+ )
+ (server_dir / "config.json").write_text(
+ json.dumps(
+ dict(
+ ipv6=True,
+ **{"log-level": "silent"},
+ listeners=listeners,
+ rules=["MATCH,DIRECT"],
+ hosts={"vcore-fixture.test": origin.ipv4},
+ )
+ )
+ )
+ origin.release()
+ origin.wait_tcp(24000)
+ server.release()
+ for index in range(len(selected)):
+ server.wait_tcp(23000 + index)
+ server.wait_tcp(23100 + index)
+ identity["version"] = command(
+ "exec", server.name, "/data/fixture/peer", "-v"
+ ).strip()
+ if (
+ command("exec", server.name, "sha256sum", "/data/fixture/peer").split()[
+ 0
+ ]
+ != identity["binary_sha256"]
+ ):
+ raise RuntimeError("Mihomo binary identity mismatch")
+ for index, name in enumerate(selected):
+ style, rtt, key = required[name]
+ encryption = (
+ f"mlkem768x25519plus.{style}.{rtt}."
+ f"{pairs[key][0]}{paddings[padding]}"
+ )
+ fixture = root / "input.json"
+ fixture.write_text(
+ json.dumps(
+ dict(
+ isolation="containers",
+ encryption=encryption,
+ force_chacha=chacha,
+ ticket_expiry=expiry,
+ node=dict(
+ name="edge",
+ type="vless",
+ server=server.ipv4,
+ port=23000 + index,
+ uuid="07070707-0707-0707-0707-070707070707",
+ udp=True,
+ encryption=encryption,
+ ),
+ origin_control=f"{origin.ipv4}:24000",
+ origin_ipv4=origin.ipv4,
+ origin_ipv6=origin.ipv6,
+ server_ipv4=server.ipv4,
+ server_ipv6=server.ipv6,
+ port=23000 + index,
+ reject_port=23100 + index,
+ )
+ )
+ )
+ argv = [
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ "encryption_wire",
+ test,
+ "--",
+ "--ignored",
+ "--exact",
+ "--nocapture",
+ ]
+ result = run_command(
+ argv,
+ env={**os.environ, "VCORE_ENCRYPTION_FIXTURE": str(fixture)},
+ timeout=150,
+ )
+ text = result.stdout.decode(errors="replace")
+ (output / f"{name}.log").write_text(redact(text))
+ passed = (
+ result.returncode == 0
+ and result.cleanup
+ and marker in text
+ and "1 passed; 0 failed; 0 ignored" in text
+ )
+ report["cases"].append(
+ dict(
+ case_id=name,
+ command=argv,
+ returncode=result.returncode,
+ cleanup=result.cleanup,
+ status="PASS" if passed else "FAIL",
+ )
+ )
+ print(f"{name}: {'PASS' if passed else 'FAIL'}", flush=True)
+ if not passed:
+ raise RuntimeError("Encryption wire gate failed")
+ origin.ensure_alive()
+ server.ensure_alive()
+ report["status"] = "PASS"
+ except KeyboardInterrupt:
+ report["status"] = "INTERRUPTED"
+ except Exception as error:
+ report["status"] = "FAIL"
+ report["error"] = redact(str(error))
+ finally:
+ report["source_after"] = source_identity()
+ report["source_unchanged"] = same_source(
+ report["source"], report["source_after"]
+ )
+ report["cleanup"] = all(
+ peer.get("joined", False) for peer in report["isolation"].get("peers", [])
+ )
+ if not report["source_unchanged"] or not report["cleanup"]:
+ report["status"] = "FAIL"
+ (output / "encryption-results.json").write_text(
+ json.dumps(report, indent=2) + "\n"
+ )
+ return 0 if report["status"] == "PASS" else 1
+
+
+if __name__ == "__main__":
+ import argparse
+ import sys
+
+ parser = argparse.ArgumentParser()
+ parser.add_argument("output", type=Path)
+ parser.add_argument("cases", nargs="*")
+ parser.add_argument("--consumer", action="store_true")
+ parser.add_argument("--chacha", action="store_true")
+ parser.add_argument("--expiry", action="store_true")
+ parser.add_argument(
+ "--padding",
+ choices=("minimal", "default", "fragmented", "maximum"),
+ default="minimal",
+ )
+ args = parser.parse_args()
+ with exclusive_run():
+ sys.exit(
+ run(
+ args.output,
+ args.cases or None,
+ consumer=args.consumer,
+ chacha=args.chacha,
+ expiry=args.expiry,
+ padding=args.padding,
+ )
+ )
diff --git a/scripts/src/vcore_scripts/protocol_encryption_public.py b/scripts/src/vcore_scripts/protocol_encryption_public.py
new file mode 100644
index 0000000..76a5b5e
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_encryption_public.py
@@ -0,0 +1,103 @@
+"""Public Encryption consumers using the existing isolated VLESS lab."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .builds import CORE_DIR
+from .protocol_encryption import cases, encode
+
+
+def configuration(profile, node, peer):
+ style, rtt, key = cases()[profile]
+ vectors = json.loads(
+ (CORE_DIR / "tests/protocols/encryption-crypto.json").read_text()
+ )
+ pairs = {
+ "x25519": (encode(vectors["x25519_public"]), encode(vectors["x25519_private"])),
+ "mlkem": (encode(vectors["mlkem_public"]), encode(vectors["mlkem_seed"])),
+ }
+ pairs["mixed"] = tuple(
+ ".".join((pairs["x25519"][i], pairs["mlkem"][i], pairs["x25519"][i]))
+ for i in (0, 1)
+ )
+ # Nontrivial fragments/gaps exercise early-data continuation, not merely
+ # the smallest one-flight padding used by the wire/replay lab.
+ padding = "100-35-35.100-1-1.100-47-47"
+ node["encryption"] = f"mlkem768x25519plus.{style}.{rtt}.{pairs[key][0]}.{padding}"
+ for listener in peer["listeners"]:
+ listener["decryption"] = (
+ f"mlkem768x25519plus.{style}.600s.{pairs[key][1]}.{padding}"
+ )
+
+
+def catalog():
+ required = {}
+ modes = (
+ "tcp",
+ "tcp-tls",
+ "tcp-reality",
+ "ws",
+ "ws-tls",
+ "ws-ed-1",
+ "ws-ed-2048",
+ "upgrade",
+ "upgrade-fast",
+ "grpc",
+ "grpc-tls",
+ "xhttp-stream-one",
+ "xhttp-stream-up",
+ "xhttp-packet-up",
+ "xhttp-stream-up-download",
+ "xhttp-packet-up-download",
+ )
+ for mode in modes:
+ tls = mode.endswith(("-tls", "-reality")) or mode.startswith("xhttp-")
+ for suffix, test in (
+ ("BASE", "public_base"),
+ ("CLOSE", "native_mihomo_close_alignment"),
+ ):
+ required[f"SECURITY-E-{mode.upper()}-{suffix}"] = ("M", mode, tls, test)
+ for mode in ("tcp-tls", "grpc-tls"):
+ for suffix, test in (
+ ("GRAPH", "runtime::public_graph"),
+ ("IPV6", "runtime::public_ipv6_and_gates"),
+ ("ENTRYPOINTS", "runtime::public_entrypoints"),
+ ("LIFE", "runtime::public_lifecycle"),
+ ("OWNED", "runtime::owned_resources"),
+ ("UDP-ISOLATION", "runtime::public_udp_isolation"),
+ ):
+ required[f"SECURITY-E-{mode.upper()}-{suffix}"] = ("M", mode, True, test)
+ for mode in ("vision-encryption", "vision-tls", "vision-reality"):
+ for suffix, test in (
+ ("BASE", "public_base"),
+ ("INNER-TLS", "native_vision_inner_tls"),
+ ("UDP", "native_vision_xudp"),
+ ("CLOSE", "native_mihomo_close_alignment"),
+ ("DIRECT-CLOSE", "native_vision_direct_close_alignment"),
+ ):
+ required[f"SECURITY-E-{mode.upper()}-{suffix}"] = (
+ "M",
+ mode,
+ mode != "vision-encryption",
+ test,
+ )
+ return required
+
+
+if __name__ == "__main__":
+ import argparse
+
+ from .mihomo_isolation import exclusive_run
+ from .protocol_vless_container import run
+
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("output", type=Path)
+ parser.add_argument("profile", choices=cases())
+ parser.add_argument("cases", nargs="*")
+ args = parser.parse_args()
+ with exclusive_run():
+ raise SystemExit(
+ run(args.output.resolve(), args.cases or None, encryption=args.profile)
+ )
diff --git a/scripts/src/vcore_scripts/protocol_evidence.py b/scripts/src/vcore_scripts/protocol_evidence.py
new file mode 100644
index 0000000..b93d29a
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_evidence.py
@@ -0,0 +1,600 @@
+"""Executable requirements and fail-closed structured result checks."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from pathlib import Path
+
+from .protocol_catalogs import (
+ CATALOG_DIR,
+ CATEGORIES,
+ FIELD_IDS,
+ SUITES,
+ _unique_object,
+)
+
+FOUNDATIONS_REQUIRED_IDS = {
+ "FOUNDATIONS-SCHEMA",
+ "FOUNDATIONS-LIMITS",
+ "FOUNDATIONS-STREAM",
+ "FOUNDATIONS-DATAGRAM",
+ "FOUNDATIONS-QUIC",
+ "FOUNDATIONS-RESOLUTION",
+ "FOUNDATIONS-RESOURCES",
+ "FOUNDATIONS-SECURITY",
+ "FOUNDATIONS-XUDP",
+ "FOUNDATIONS-REGRESSION",
+ "FOUNDATIONS-M-WS",
+ "FOUNDATIONS-M-WSS",
+ "FOUNDATIONS-M-GRPC",
+ "FOUNDATIONS-M-GRPC-TLS",
+ "FOUNDATIONS-M-WS-ED",
+ "FOUNDATIONS-V2-HTTP",
+ "FOUNDATIONS-V2-H2",
+ "FOUNDATIONS-V2-WS-HEADER",
+ "FOUNDATIONS-V2-WS-PATH",
+ "FOUNDATIONS-FEATURES",
+ "FOUNDATIONS-SCRIPTS",
+}
+HEX = re.compile(r"[0-9a-f]{64}")
+RESOURCE_KINDS = {
+ "task",
+ "socket",
+ "session",
+ "association",
+ "reassembly",
+ "pool",
+ "waiter",
+ "handshake",
+}
+
+
+def idle_resources(snapshot) -> bool:
+ if not isinstance(snapshot, dict) or not isinstance(snapshot.get("counts"), list):
+ return False
+ counts = snapshot["counts"]
+ return (
+ len(counts) == len(RESOURCE_KINDS)
+ and all(isinstance(count, dict) for count in counts)
+ and {count.get("kind") for count in counts} == RESOURCE_KINDS
+ and all(
+ type(count.get("current")) is int
+ and count["current"] == 0
+ and type(count.get("peak")) is int
+ and count["peak"] >= 0
+ for count in counts
+ )
+ )
+
+
+def read_events(path: Path) -> list[dict]:
+ if path.stat().st_size > 4 * 1024 * 1024:
+ raise ValueError("case events exceeded bound")
+ events = [
+ json.loads(line, object_pairs_hook=_unique_object)
+ for line in path.read_text().splitlines()
+ ]
+ if not all(isinstance(event, dict) for event in events):
+ raise ValueError("malformed structured case event")
+ return events
+
+
+def read_json(path: Path):
+ if path.stat().st_size > 4 * 1024 * 1024:
+ raise ValueError("protocol evidence exceeds bounded document size")
+ return json.loads(
+ path.read_text(encoding="utf-8"), object_pairs_hook=_unique_object
+ )
+
+
+def executable_cases() -> list[dict]:
+ """Single source: retained foundation fixtures plus current protocol catalogs."""
+ from .protocol_hysteria2_catalog import definitions as hysteria2
+ from .protocol_integration_catalog import definitions as integration
+ from .protocol_security_catalog import definitions as security
+ from .protocol_vless_acceptance import definitions as vless
+ from .protocol_vmess_acceptance import definitions as vmess
+ from .protocol_xhttp_acceptance import definitions as xhttp
+
+ foundation = read_json(CATALOG_DIR / "foundation-cases.json")["cases"]
+ return foundation + [
+ case
+ for define in (vmess, vless, xhttp, hysteria2, security, integration)
+ for case in define()
+ ]
+
+
+def load_manifest(path: Path | None = None) -> list[dict]:
+ expected = executable_cases()
+ data = (
+ read_json(path)
+ if path is not None
+ else {
+ "schema_version": 1,
+ "kind": "executable-case-manifest",
+ "cases": expected,
+ }
+ )
+ if (
+ not isinstance(data, dict)
+ or type(data.get("schema_version")) is not int
+ or data.get("schema_version") != 1
+ or data.get("kind") != "executable-case-manifest"
+ ):
+ raise ValueError("unsupported executable case manifest")
+ cases = data.get("cases")
+ if not isinstance(cases, list) or not cases:
+ raise ValueError("empty executable case manifest")
+ seen = set()
+ for case in cases:
+ required = {
+ "case_id",
+ "stage",
+ "substage",
+ "required",
+ "row_ids",
+ "protocol",
+ "network",
+ "security",
+ "udp_codec",
+ "field_values",
+ "outer_family",
+ "inner_family",
+ "target_type",
+ "upstream_graph",
+ "peer_kind",
+ "peer_config",
+ "gap_source",
+ "expected_observation",
+ "required_evidence",
+ "prerequisites",
+ "runner",
+ "timeout_seconds",
+ }
+ if not isinstance(case, dict) or not required <= case.keys():
+ raise ValueError("incomplete executable case metadata")
+ identifier = case["case_id"]
+ if (
+ not isinstance(identifier, str)
+ or not re.fullmatch(r"[A-Z0-9-]+", identifier)
+ or identifier in seen
+ ):
+ raise ValueError("invalid or duplicate executable case ID")
+ seen.add(identifier)
+ if (
+ case["stage"] not in SUITES
+ or case["substage"] not in CATEGORIES
+ or not case["substage"].startswith(case["stage"] + ".")
+ ):
+ raise ValueError("invalid case ownership")
+ if (
+ type(case["required"]) is not bool
+ or not isinstance(case["row_ids"], list)
+ or len(set(case["row_ids"])) != len(case["row_ids"])
+ or not set(case["row_ids"]) <= FIELD_IDS
+ ):
+ raise ValueError("invalid required flag or field references")
+ if case["peer_kind"] not in {"M", "H", "XR", "V2", "SS", "unit"}:
+ raise ValueError("unknown peer kind")
+ for key in ["expected_observation", "required_evidence", "prerequisites"]:
+ items = case[key]
+ if (
+ not isinstance(items, list)
+ or not items
+ or not all(isinstance(item, str) and item for item in items)
+ or len(items) != len(set(items))
+ ):
+ raise ValueError("empty or duplicate executable observations")
+ if (
+ not isinstance(case["field_values"], dict)
+ or not isinstance(case["peer_config"], dict)
+ or type(case["timeout_seconds"]) is not int
+ or not 1 <= case["timeout_seconds"] <= 3600
+ ):
+ raise ValueError("invalid case bounds or configuration reference")
+ if {
+ case["case_id"]
+ for case in cases
+ if case["stage"] == "FOUNDATIONS" and case["required"]
+ } != FOUNDATIONS_REQUIRED_IDS:
+ raise ValueError("FOUNDATIONS required set was removed, renamed or downgraded")
+ from .protocol_trojan_acceptance import REQUIRED_IDS
+
+ if {
+ case["case_id"]
+ for case in cases
+ if case["stage"] == "TROJAN" and case["required"]
+ } != REQUIRED_IDS:
+ raise ValueError("TROJAN required set was removed, renamed or downgraded")
+ if cases != expected:
+ raise ValueError("manifest differs from the current executable catalog")
+ return cases
+
+
+def check_limit_references(
+ cases: list[dict], path: Path = CATALOG_DIR / "limits.json"
+) -> None:
+ limits = read_json(path)
+ identifiers = {case["case_id"] for case in cases}
+ if (
+ limits.get("schema_version") != 1
+ or limits.get("kind") != "runtime-limit-registry"
+ ):
+ raise ValueError("unsupported runtime limit registry")
+ entries = limits.get("limits", [])
+ names = [entry.get("id") for entry in entries]
+ if not entries or len(names) != len(set(names)):
+ raise ValueError("empty or duplicate runtime limits")
+ for entry in entries:
+ if (
+ not entry.get("boundary_cases")
+ or not set(entry["boundary_cases"]) <= identifiers
+ ):
+ raise ValueError("runtime limit has no executable boundary case")
+
+
+def select_cases(
+ cases: list[dict],
+ *,
+ stage: str,
+ identifiers: list[str] | None = None,
+ protocol: str | None = None,
+) -> list[dict]:
+ if identifiers and (
+ len(identifiers) != len(set(identifiers))
+ or not set(identifiers) <= {case["case_id"] for case in cases}
+ ):
+ raise ValueError("duplicate or unknown requested case")
+ selected = [
+ case
+ for case in cases
+ if case["stage"] == stage
+ and case["required"]
+ and (not identifiers or case["case_id"] in identifiers)
+ and (protocol is None or case["protocol"] == protocol)
+ ]
+ if not selected:
+ raise ValueError("selection has no executable required cases; stage is NOT RUN")
+ if identifiers and {case["case_id"] for case in selected} != set(identifiers):
+ raise ValueError("case selection conflicts with stage or protocol")
+ return selected
+
+
+def validate_results(required: list[dict], results: list[dict]) -> None:
+ if not required:
+ raise ValueError("empty required result set")
+ expected = {case["case_id"]: case for case in required}
+ identifiers = [result.get("case_id") for result in results]
+ if len(identifiers) != len(set(identifiers)) or set(identifiers) != set(expected):
+ raise ValueError("missing, duplicate or unknown case result")
+ for result in results:
+ case = expected[result["case_id"]]
+ if (
+ result.get("status") != "PASS"
+ or result.get("cleanup") is not True
+ or type(result.get("command_exit_code")) is not int
+ or result["command_exit_code"] != 0
+ ):
+ raise ValueError(
+ "required case failed, was blocked/not run, or did not clean up"
+ )
+ observations = result.get("assertions", {})
+ if (
+ not isinstance(observations, dict)
+ or set(observations) != set(case["expected_observation"])
+ or not all(value is True for value in observations.values())
+ ):
+ raise ValueError("missing or false required behavioral assertion")
+ evidence = result.get("evidence", [])
+ if (
+ not isinstance(evidence, list)
+ or len(evidence) != len(set(evidence))
+ or set(evidence) != set(case["required_evidence"])
+ ):
+ raise ValueError(
+ "incomplete behavior evidence; CFG alone is not acceptance"
+ )
+ if (
+ result.get("row_ids") != case["row_ids"]
+ or result.get("peer_kind") != case["peer_kind"]
+ or result.get("scope")
+ != (
+ "protocol-consumer"
+ if case["stage"]
+ in {
+ "TROJAN",
+ "VMESS",
+ "VLESS",
+ "XHTTP",
+ "HYSTERIA2",
+ "SECURITY",
+ "INTEGRATION",
+ }
+ else "foundation-only"
+ )
+ ):
+ raise ValueError("case mapping or evidence scope differs from manifest")
+
+
+def rust_results(case: dict, events: list[dict], returncode: int) -> dict:
+ observed = [
+ event
+ for event in events
+ if event.get("suite") == case.get("event_suite", case["case_id"])
+ ]
+ names = case["expected_observation"]
+ assertions = {name: False for name in names}
+ unknown = any(
+ event.get("assertion") not in assertions or event.get("schema_version") != 1
+ for event in observed
+ )
+ for name in names:
+ entries = [event for event in observed if event.get("assertion") == name]
+ assertions[name] = len(entries) == 2 and [
+ entry.get("status") for entry in entries
+ ] == ["BEGIN", "PASS"]
+ if assertions[name] and "resources" in case["required_evidence"]:
+ assertions[name] = idle_resources(entries[-1].get("resources"))
+ result = new_result(case)
+ result.update(assertions=assertions, command_exit_code=returncode, cleanup=True)
+ result["status"] = (
+ "PASS"
+ if not unknown and returncode == 0 and all(assertions.values())
+ else "FAIL"
+ )
+ if result["status"] == "PASS":
+ result["evidence"] = [
+ item for item in case["required_evidence"] if item != "peer-identity"
+ ]
+ return result
+
+
+def new_result(case: dict) -> dict:
+ return {
+ "case_id": case["case_id"],
+ "row_ids": case["row_ids"],
+ "peer_kind": case["peer_kind"],
+ "scope": "protocol-consumer"
+ if case["stage"]
+ in {"TROJAN", "VMESS", "VLESS", "XHTTP", "HYSTERIA2", "SECURITY", "INTEGRATION"}
+ else "foundation-only",
+ "status": "NOT RUN",
+ "assertions": {},
+ "evidence": [],
+ "cleanup": False,
+ "command_exit_code": None,
+ }
+
+
+def artifact(run_dir: Path, relative: str, digest: str) -> Path:
+ path = run_dir / relative
+ if (
+ Path(relative).is_absolute()
+ or ".." in Path(relative).parts
+ or path.is_symlink()
+ or not path.resolve().is_relative_to(run_dir.resolve())
+ or not HEX.fullmatch(digest)
+ ):
+ raise ValueError("unsafe evidence path or invalid hash")
+ with path.open("rb") as stream:
+ actual = hashlib.file_digest(stream, "sha256").hexdigest()
+ if actual != digest:
+ raise ValueError("evidence content hash mismatch")
+ return path
+
+
+def check_run(run_dir: Path, stage: str, manifest: Path | None = None) -> None:
+ if manifest is None and (run_dir / "manifest.json").is_file():
+ manifest = run_dir / "manifest.json"
+ cases = load_manifest(manifest)
+ check_limit_references(cases)
+ required = select_cases(cases, stage=stage)
+ run = read_json(run_dir / "run.json")
+ result = read_json(run_dir / "cases.json")
+ peers = read_json(run_dir / "peers.json")
+ if (
+ run.get("stage") != stage
+ or run.get("mode") != "execute"
+ or run.get("cleanup") is not True
+ or run.get("source_unchanged") is not True
+ or run.get("selected_cases") != [case["case_id"] for case in required]
+ ):
+ raise ValueError(
+ "partial/preflight run or changing source cannot sign off the stage"
+ )
+ for key in ["source_tree_sha256", "lock_sha256", "dirty_patch_sha256"]:
+ if not isinstance(run.get(key), str) or not HEX.fullmatch(run[key]):
+ raise ValueError("missing immutable input identity")
+ validate_results(required, result)
+ artifacts = run.get("artifacts", [])
+ paths = [entry["path"] for entry in artifacts]
+ if len(paths) != len(set(paths)):
+ raise ValueError("duplicate evidence artifact")
+ if stage in {
+ "TROJAN",
+ "VMESS",
+ "VLESS",
+ "XHTTP",
+ "HYSTERIA2",
+ "SECURITY",
+ "INTEGRATION",
+ }:
+ if stage == "TROJAN":
+ from .protocol_trojan_acceptance import check
+ elif stage == "VMESS":
+ from .protocol_vmess_acceptance import check
+ elif stage == "VLESS":
+ from .protocol_vless_acceptance import check
+ elif stage == "XHTTP":
+ from .protocol_xhttp_acceptance import check
+ elif stage == "HYSTERIA2":
+ from .protocol_hysteria2_acceptance import check
+ elif stage == "SECURITY":
+ from .protocol_security_acceptance import check
+ else:
+ from .protocol_integration_acceptance import check
+
+ for evidence in artifacts:
+ artifact(run_dir, evidence["path"], evidence["sha256"])
+ check(run_dir, required, run, result, peers, paths)
+ return
+ necessary = {
+ "cases.json",
+ "peers.json",
+ "resources.jsonl",
+ "summary.md",
+ "rust-events.jsonl",
+ "legacy-events.jsonl",
+ "native/stream-cases.json",
+ "script-tests.json",
+ }
+ if not necessary <= set(paths):
+ raise ValueError("missing persisted behavior artifacts")
+ for evidence in artifacts:
+ artifact(run_dir, evidence["path"], evidence["sha256"])
+ commands = run.get("commands", [])
+ command_names = [command.get("name") for command in commands]
+ required_commands = {
+ "rust-foundations",
+ "native-probe-build",
+ "legacy-mihomo",
+ "offline-scripts",
+ "feature-default",
+ "feature-minimal",
+ "feature-outbound-trojan",
+ "feature-outbound-vmess",
+ "feature-outbound-hysteria2",
+ "feature-stream-transport",
+ "feature-quic-transport",
+ }
+ if (
+ len(command_names) != len(set(command_names))
+ or set(command_names) != required_commands
+ or any(
+ type(command.get("exit_code")) is not int
+ or command["exit_code"] != 0
+ or command.get("cleanup") is not True
+ for command in commands
+ )
+ ):
+ raise ValueError("missing, failed or unjoined acceptance command")
+ for command in commands:
+ if command.get("log") and command["log"] not in paths:
+ raise ValueError("command log has no content identity")
+ rust_events = read_events(run_dir / "rust-events.jsonl")
+ legacy_events = read_events(run_dir / "legacy-events.jsonl")
+ native = read_json(run_dir / "native/stream-cases.json")
+ native_cases = [case for case in required if case["runner"] == "native-stream"]
+ if [item.get("case_id") for item in native.get("cases", [])] != [
+ case["case_id"] for case in native_cases
+ ]:
+ raise ValueError("missing, duplicate or unknown native case evidence")
+ # Use exactly the same structured evaluators as execution, never console text.
+ from .protocol_harness import SCRIPT_OBSERVATIONS, _native_results
+
+ recalculated = _native_results(native_cases, native)
+ for case in required:
+ if case["runner"] in {"rust", "mihomo-legacy"}:
+ calculated = rust_results(
+ case,
+ legacy_events if case["runner"] == "mihomo-legacy" else rust_events,
+ 0,
+ )
+ if case["runner"] == "mihomo-legacy" and calculated["status"] == "PASS":
+ calculated["evidence"] = case["required_evidence"]
+ recalculated.append(calculated)
+ actual = {item["case_id"]: item for item in result}
+ for calculated in recalculated:
+ for key in ["status", "assertions", "evidence", "cleanup", "command_exit_code"]:
+ if actual[calculated["case_id"]].get(key) != calculated[key]:
+ raise ValueError(
+ "case result disagrees with original structured evidence"
+ )
+ script = read_json(run_dir / "script-tests.json")
+ scripts = script.get("cases", [])
+ tests = {entry["test"]: entry["status"] for entry in scripts}
+ if (
+ not scripts
+ or len(tests) != len(scripts)
+ or len(tests) != script.get("tests_run")
+ or any(status != "PASS" for status in tests.values())
+ or any(
+ tests.get(identifier) != "PASS"
+ for identifier in SCRIPT_OBSERVATIONS.values()
+ )
+ ):
+ raise ValueError("missing or failed offline harness failure-path proof")
+ resources = read_events(run_dir / "resources.jsonl")
+ if not resources or not all(
+ idle_resources(event.get("resources")) for event in resources
+ ):
+ raise ValueError("missing, nonidle or malformed owned resource evidence")
+ resource_passes = [
+ event
+ for event in rust_events
+ if event.get("suite") == "FOUNDATIONS-RESOURCES"
+ and event.get("status") == "PASS"
+ ]
+ for event in resource_passes:
+ checkpoints = event.get("checkpoints", [])
+ by_phase = {point["phase"]: point["resources"] for point in checkpoints}
+ if (
+ len(checkpoints) != len(by_phase)
+ or not {"baseline", "after-stop"} <= by_phase.keys()
+ or not idle_resources(by_phase["baseline"])
+ or not idle_resources(by_phase["after-stop"])
+ ):
+ raise ValueError("resource ownership has no baseline/Stop evidence")
+ if "remain_quiet" in event["assertion"] and (
+ by_phase.get("quiet") != by_phase["after-stop"]
+ or event.get("seconds", 0) < 5
+ ):
+ raise ValueError("resource quiet-window evidence missing")
+ for case in required:
+ if "peer-identity" in case["required_evidence"]:
+ matches = [
+ peer
+ for peer in peers
+ if peer.get("kind") == case["peer_kind"]
+ and peer.get("status") == "READY"
+ ]
+ if (
+ len(matches) != 1
+ or not matches[0].get("version")
+ or not HEX.fullmatch(matches[0].get("binary_sha256", ""))
+ or not HEX.fullmatch(matches[0].get("archive_sha256", ""))
+ or not matches[0]
+ .get("source_url", "")
+ .startswith("https://github.com/")
+ ):
+ raise ValueError("missing official peer identity")
+ if case["runner"] == "native-stream":
+ native_peers = [
+ peer
+ for peer in native.get("peers", [])
+ if peer.get("kind") == case["peer_kind"]
+ ]
+ if (
+ len(native_peers) != 1
+ or native_peers[0].get("binary_sha256")
+ != matches[0]["binary_sha256"]
+ ):
+ raise ValueError("case used a different peer from preflight")
+ if case["runner"] == "mihomo-legacy":
+ peer = matches[0]
+ if (
+ peer.get("container_status") != "READY"
+ or not HEX.fullmatch(
+ peer.get("container_artifact", {}).get("binary_sha256", "")
+ )
+ or peer["container_artifact"].get("release") != peer.get("release")
+ ):
+ raise ValueError(
+ "legacy peer did not use the same official release snapshot"
+ )
+ print(
+ f"{stage}: PASS ({len(required)} required foundation cases); "
+ "production field consumers remain NOT RUN"
+ )
diff --git a/scripts/src/vcore_scripts/protocol_fingerprint.py b/scripts/src/vcore_scripts/protocol_fingerprint.py
new file mode 100644
index 0000000..1ca5339
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_fingerprint.py
@@ -0,0 +1,177 @@
+"""Named-profile VCore integration, reusing the owned container wire harness."""
+
+import argparse
+import hashlib
+import json
+import sys
+import time
+from datetime import UTC, datetime
+from pathlib import Path
+
+from .mihomo_isolation import exclusive_run
+from .protocol_inputs import same_source, source_identity
+from .protocol_vless_container import CLIENT_FINGERPRINTS, run
+
+SELECTED_TIMEOUT_SECONDS = 3600
+
+CASES = [
+ "FINGERPRINT-ANYTLS",
+ *[
+ f"VLESS-REGRESSION-{protocol}-{network}"
+ for protocol in ("TROJAN", "VMESS")
+ for network in ("TCP", "WS", "GRPC")
+ ],
+ *[
+ f"VLESS-{mode}-BASE"
+ for mode in (
+ "TCP-TLS",
+ "WS-TLS",
+ "WS-ED-1-TLS",
+ "WS-ED-2048-TLS",
+ "WS-HEADER-TLS",
+ "WS-PATH-TLS",
+ "UPGRADE-TLS",
+ "UPGRADE-FAST-TLS",
+ "HTTP-TLS",
+ "H2-TLS",
+ "GRPC-TLS",
+ "TCP-REALITY",
+ "WS-REALITY",
+ "UPGRADE-REALITY",
+ "UPGRADE-FAST-REALITY",
+ "GRPC-REALITY",
+ "XHTTP-STREAM-ONE",
+ "XHTTP-STREAM-UP",
+ "XHTTP-PACKET-UP",
+ "XHTTP-STREAM-ONE-REALITY",
+ "XHTTP-STREAM-UP-DOWNLOAD-REALITY",
+ "VISION-TLS",
+ "VISION-REALITY",
+ )
+ ],
+ "VLESS-VISION-TLS-INNER-TLS",
+ "FINGERPRINT-VMESS-HTTP-TLS",
+ "FINGERPRINT-VMESS-H2-TLS",
+ "VLESS-VISION-REALITY-INNER-TLS",
+ "VLESS-TCP-REALITY-NEG",
+ "VLESS-TCP-TLS-NEG",
+ "VLESS-GRPC-MTLS-IDENTITY",
+ "VLESS-WS-ALPN-TLS-NEG",
+ "VLESS-TCP-TLS-CLOSE",
+ "VLESS-TCP-REALITY-CLOSE",
+ "VLESS-GRPC-REALITY-CLOSE",
+ "VLESS-VISION-REALITY-CLOSE",
+ "VLESS-GRPC-TLS-LIFE",
+ "VLESS-GRPC-TLS-OWNED",
+ "VLESS-VISION-REALITY-LIFE",
+ "VLESS-VISION-REALITY-OWNED",
+]
+
+
+def run_selected(output, profile):
+ from .builds import CORE_DIR
+ from .protocol_xhttp_fields import run as run_xhttp
+ from .protocol_xhttp_fields import selected_profile_variants
+
+ if (
+ profile not in CLIENT_FINGERPRINTS
+ or output.parent != CORE_DIR / "target/interop/runs"
+ ):
+ raise ValueError("use a supported profile and fresh target/interop/runs child")
+ output.mkdir(parents=True, exist_ok=False)
+ started = time.monotonic()
+ report = dict(
+ stage="FINGERPRINT-INTEROP",
+ scope="selected-transports",
+ profile=profile,
+ source=source_identity(),
+ status="NOT RUN",
+ parts=[],
+ started_utc=datetime.now(UTC).isoformat(),
+ timeout_seconds=SELECTED_TIMEOUT_SECONDS,
+ )
+ try:
+ for phase in ("transports", "xhttp"):
+ if phase == "transports":
+ result = run(output / phase, CASES, client_fingerprint=profile)
+ path = output / phase / "vless-results.json"
+ else:
+ selected = [
+ f"{version}-{mode}-headers"
+ for version in ("h1", "h2")
+ for mode in ("stream-one", "stream-up", "packet-up")
+ ]
+ selected.extend(selected_profile_variants(profile))
+ jobs = {
+ name: [
+ dict(
+ case_id=f"FINGERPRINT-{profile}-{name}",
+ test="security::native_xhttp_security"
+ if name.endswith("reject-pin")
+ else "public_base",
+ )
+ ]
+ for name in selected
+ }
+ result = run_xhttp(
+ output / phase, selected, jobs=jobs, client_fingerprint=profile
+ )
+ path = output / phase / "xhttp-fields-results.json"
+ part = json.loads(path.read_text())
+ report["parts"].append(
+ dict(
+ phase=phase,
+ report=str(path.relative_to(output)),
+ sha256=hashlib.sha256(path.read_bytes()).hexdigest(),
+ status=part["status"],
+ cleanup=part["cleanup"],
+ source_unchanged=part["source_unchanged"],
+ cases=len(part["cases"]),
+ )
+ )
+ if result:
+ raise RuntimeError(f"{phase} gate failed")
+ report["status"] = "PASS"
+ except (OSError, ValueError, RuntimeError) as error:
+ report.update(status="FAIL", reason=str(error))
+ finally:
+ report["finished_utc"] = datetime.now(UTC).isoformat()
+ report["seconds"] = round(time.monotonic() - started, 3)
+ report["source_after"] = source_identity()
+ # Staging an already captured untracked file changes the diagnostic
+ # Git patch, not the exhaustive path/content source-tree digest.
+ report["source_unchanged"] = same_source(
+ report["source"], report["source_after"]
+ )
+ if not report["source_unchanged"]:
+ report["status"] = "FAIL"
+ if report["seconds"] > SELECTED_TIMEOUT_SECONDS:
+ report.update(
+ status="FAIL", reason="selected transport suite deadline exceeded"
+ )
+ (output / "fingerprint-results.json").write_text(
+ json.dumps(report, indent=2) + "\n"
+ )
+ return 0 if report["status"] == "PASS" else 1
+
+
+def main(argv=None):
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("output", type=Path)
+ parser.add_argument("cases", nargs="*")
+ parser.add_argument(
+ "--client-fingerprint", choices=CLIENT_FINGERPRINTS, default="chrome120"
+ )
+ args = parser.parse_args(argv)
+ with exclusive_run():
+ if not args.cases:
+ return run_selected(args.output.resolve(), args.client_fingerprint)
+ return run(
+ args.output.resolve(),
+ args.cases or CASES,
+ client_fingerprint=args.client_fingerprint,
+ )
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/src/vcore_scripts/protocol_fingerprint_reference.py b/scripts/src/vcore_scripts/protocol_fingerprint_reference.py
new file mode 100644
index 0000000..37f73f2
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_fingerprint_reference.py
@@ -0,0 +1,551 @@
+"""Selected-v1 reference ClientHello acquisition; not VCore interoperability."""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import contextlib
+import copy
+import json
+import secrets
+import shutil
+import signal
+import sys
+import tempfile
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+from .builds import CORE_DIR
+from .mihomo_isolation import exclusive_run
+from .mihomo_release import download_mihomo
+from .protocol_containers import ContainerLab, command, listing
+from .protocol_fixtures import certificates
+from .protocol_inputs import redact, source_identity
+from .protocol_peers import run_command
+from .tls_client_hello import is_grease, parse_client_hello, validate_capture
+
+PROFILES = ("chrome", "chrome120", "firefox", "firefox120", "safari", "safari16")
+TEMPLATES = {
+ "chrome": "Chrome133",
+ "chrome120": "Chrome120",
+ "firefox": "Firefox120",
+ "firefox120": "Firefox120",
+ "safari": "Safari16.0",
+ "safari16": "Safari16.0",
+}
+SNIS = ("fingerprint.test", "f" * 63 + ".fingerprint.test")
+PORTS = {
+ "tcp": 24430,
+ "ws": 24430,
+ "grpc": 24430,
+ "reality": 24430,
+ "tls13": 24431,
+ "tls12": 24432,
+}
+
+
+def reference_cases() -> list[dict]:
+ """The public reference-case catalog; a listing does not start a peer."""
+ cases = []
+ for profile in (*PROFILES, "none"):
+ contexts = ("tcp",) if profile == "none" else ("tcp", "ws", "grpc", "reality")
+ for context in contexts:
+ for sni in SNIS:
+ for attempt in range(2):
+ cases.append(
+ dict(
+ id=f"FINGERPRINT-REFERENCE-{profile}-{context}-"
+ f"{len(sni)}-{attempt}",
+ profile=profile,
+ template=TEMPLATES.get(profile),
+ context=context,
+ sni=sni,
+ sni_length=len(sni),
+ attempt=attempt,
+ )
+ )
+ for profile in ("chrome", "chrome120", "firefox", "safari"):
+ for context in ("tls12", "tls13"):
+ for attempt in range(2):
+ cases.append(
+ dict(
+ id=f"FINGERPRINT-REFERENCE-{profile}-{context}-16-{attempt}",
+ profile=profile,
+ template=TEMPLATES[profile],
+ context=context,
+ sni=SNIS[0],
+ sni_length=16,
+ attempt=attempt,
+ )
+ )
+ return cases
+
+
+def _reference_shape(hello, case, *, expected_alpn=None, allow_psk=False):
+ """Apply only source-defined reference variations, checking before masking."""
+ shape = copy.deepcopy(hello)
+ shape.pop("raw_sha256")
+ size = shape.pop("bytes")
+ padding = next((e for e in shape["extensions"] if e["type"] == 21), None)
+ psk = next((e for e in shape["extensions"] if e["type"] == 41), None)
+ if psk and (not allow_psk or shape["extensions"][-1] != psk):
+ raise ValueError("unexpected PSK or invalid last-extension position")
+ unpadded = size - (padding["bytes"] + 4 if padding else 0)
+ needs_padding = (
+ case["template"] in {"Chrome120", "Safari16.0"} and 255 < unpadded < 512
+ )
+ if bool(padding) != needs_padding:
+ raise ValueError("reference padding presence differs from template")
+ if padding:
+ expected = max(1, 512 - unpadded - 4)
+ if (
+ padding["bytes"] != expected
+ or padding["payload_hex"] != "00" * expected
+ or shape["extensions"][-2 if psk else -1] != padding
+ ):
+ raise ValueError("reference padding contents, position or size mismatch")
+ shape["extensions"].remove(padding)
+ groups = next(e["values"] for e in shape["extensions"] if e["type"] == 10)
+ shares = next(e["shares"] for e in shape["extensions"] if e["type"] == 51)
+ if any(s["group"] not in groups for s in shares):
+ raise ValueError("reference key share/group correlation mismatch")
+ for row in shape["extensions"]:
+ if row["type"] == 0:
+ if row["names"] != [dict(type=0, name=case["sni"])]:
+ raise ValueError("reference SNI mismatch")
+ row["names"], row["bytes"] = "synthetic-sni", "sni-dependent"
+ elif row["type"] == 16:
+ expected = expected_alpn or (
+ ["http/1.1"] if case["context"] == "ws" else ["h2", "http/1.1"]
+ )
+ if row["protocols"] != expected:
+ raise ValueError("reference transport ALPN mismatch")
+ row["protocols"], row["bytes"] = "transport-alpn", "alpn-dependent"
+ elif row["type"] == 65037:
+ firefox = case["template"] == "Firefox120"
+ if (
+ (row["hello_type"], row["kdf"], row["enc_bytes"]) != (0, 1, 32)
+ or row["aead"] not in ({1, 3} if firefox else {1})
+ or row["payload_bytes"]
+ not in ({239} if firefox else {144, 176, 208, 240})
+ or row["bytes"] != 42 + row["payload_bytes"]
+ ):
+ raise ValueError(
+ "reference ECH GREASE differs from source-defined variants"
+ )
+ row["aead"], row["payload_bytes"], row["bytes"] = (
+ "checked-variant",
+ "checked-variant",
+ "checked-variant",
+ )
+ for key in ("values",):
+ if key in row:
+ row[key] = ["GREASE" if is_grease(v) else v for v in row[key]]
+ if row["type"] == 51:
+ for share in row["shares"]:
+ if is_grease(share["group"]):
+ share["group"] = "GREASE"
+ if is_grease(row["type"]):
+ row["type"] = "GREASE"
+ shape["ciphers"] = ["GREASE" if is_grease(v) else v for v in shape["ciphers"]]
+ if case["template"].startswith("Chrome"):
+ rows = shape["extensions"]
+ if rows[0] != dict(type="GREASE", bytes=0, payload_hex="") or rows[
+ -2 if psk else -1
+ ] != dict(type="GREASE", bytes=1, payload_hex="00"):
+ raise ValueError("reference Chrome GREASE positions changed")
+ shape["extensions"] = [
+ rows[0],
+ *sorted(rows[1 : -2 if psk else -1], key=lambda e: e["type"]),
+ *rows[-2 if psk else -1 :],
+ ]
+ return shape
+
+
+def check_reference_report(report: dict) -> dict:
+ """Verify reference scope, raw observations and source-defined variations."""
+ if (
+ report.get("scope") != "selected-v1"
+ or report.get("status") != "CAPTURED"
+ or report.get("selection") != "full"
+ or report.get("cleanup") is not True
+ or report.get("source_unchanged") is not True
+ ):
+ raise ValueError("incomplete or unclean selected-profile reference run")
+ if report.get("source") != report.get("source_after"):
+ raise ValueError("reference source changed during capture")
+ catalog = {case["id"]: case for case in reference_cases()}
+ cases = report["cases"]
+ if len(cases) != len(catalog) or {c["id"] for c in cases} != catalog.keys():
+ raise ValueError("missing or duplicate reference cases")
+ fixtures = json.loads(
+ (CORE_DIR / "tests/fingerprints/mihomo-selected-v1.json").read_text()
+ )
+ baselines = {}
+ for sample in fixtures["samples"]:
+ case = catalog[sample["case_id"]]
+ baselines[(sample["profile"], sample["context"])] = _reference_shape(
+ validate_capture(sample), case
+ )
+ observed, tls_handshakes = 0, 0
+ for row in cases:
+ case = catalog[row["id"]]
+ if (
+ any(row.get(key) != value for key, value in case.items())
+ or row["status"] != "CAPTURED"
+ or not 1 <= len(row["observations"]) <= 4
+ ):
+ raise ValueError("reference case metadata or observations changed")
+ for event in row["observations"]:
+ hello = validate_capture(event)
+ expected = (
+ "tls-handshake-complete"
+ if case["context"] in {"tls12", "tls13"}
+ else "captured-only"
+ )
+ if event["status"] != expected or event["port"] != PORTS[case["context"]]:
+ raise ValueError("reference observation has wrong outcome")
+ if expected == "tls-handshake-complete":
+ version = "TLSv1.2" if case["context"] == "tls12" else "TLSv1.3"
+ if event["version"] != version:
+ raise ValueError("reference negotiated wrong TLS version")
+ tls_handshakes += 1
+ if case["profile"] != "none":
+ profile = {"firefox120": "firefox", "safari16": "safari"}.get(
+ case["profile"], case["profile"]
+ )
+ context = "reality" if case["context"] == "reality" else "tcp"
+ if _reference_shape(hello, case) != baselines[(profile, context)]:
+ raise ValueError(f"reference structure changed: {case['id']}")
+ observed += 1
+ return dict(
+ scope="selected-v1",
+ stage="FINGERPRINT-REFERENCE",
+ status="BASELINE VERIFIED",
+ cases=len(cases),
+ observations=observed,
+ tls_only_handshakes=tls_handshakes,
+ business_interoperability="NOT TESTED",
+ production_support="UNCHANGED",
+ )
+
+
+def _name(case):
+ return f"{case['profile']}-{case['context']}-{case['sni_length']}"
+
+
+def _node(case, server):
+ context = case["context"]
+ node = dict(
+ name=_name(case),
+ type="vless",
+ server=server,
+ port=PORTS[context],
+ uuid="07070707-0707-0707-0707-070707070707",
+ tls=True,
+ servername=case["sni"],
+ network=context if context in {"ws", "grpc"} else "tcp",
+ alpn=["h2", "http/1.1"],
+ **{"client-fingerprint": case["profile"]},
+ )
+ if context == "reality":
+ # Public RFC 7748 test vector; observer never authenticates REALITY.
+ public = bytes.fromhex(
+ "de9edb7d7b7dc1b4d35b61c2ece435373f8343c85b78674dadfc7e146f882b4f"
+ )
+ node["reality-opts"] = {
+ "public-key": base64.urlsafe_b64encode(public).decode().rstrip("="),
+ "short-id": "01020304",
+ }
+ else:
+ node["skip-cert-verify"] = True
+ if context == "ws":
+ node["ws-opts"] = {"path": "/capture"}
+ elif context == "grpc":
+ node["grpc-opts"] = {"grpc-service-name": "capture"}
+ return node
+
+
+def _probe(client, case, target, secret):
+ query = urllib.parse.urlencode(dict(url=f"http://{target}:80/", timeout=3000))
+ request = urllib.request.Request(
+ f"http://{client}:25000/proxies/{_name(case)}/delay?{query}",
+ headers={"Authorization": "Bearer " + secret},
+ )
+ opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+ try:
+ response = opener.open(request, timeout=5)
+ except urllib.error.HTTPError as error:
+ response = error
+ with response:
+ body = response.read(4097)
+ if len(body) > 4096:
+ raise ValueError("reference controller response limit")
+ # This observer cannot serve VLESS or a URL: delay failure is expected.
+ return dict(delay_http_status=response.status, business_result="NOT TESTED")
+
+
+def _events(observer, after):
+ query = (
+ "import json,pathlib,sys; p=pathlib.Path('/data/events.jsonl'); "
+ "assert p.stat().st_size <= 8*1024*1024; "
+ "print(json.dumps(p.read_text().splitlines()[int(sys.argv[1]):]))"
+ )
+ lines = json.loads(
+ command("exec", observer.name, "python", "-c", query, str(after))
+ )
+ return [json.loads(line) for line in lines]
+
+
+def run_reference(output: Path, selected=None) -> int:
+ catalog = {case["id"]: case for case in reference_cases()}
+ ids = list(catalog) if selected is None else selected
+ if not ids or len(set(ids)) != len(ids) or not set(ids) <= catalog.keys():
+ raise ValueError("invalid reference capture selection")
+ output = output.resolve()
+ if output.parent != CORE_DIR / "target/interop/runs" or output.exists():
+ raise ValueError("fresh in-repository reference run directory required")
+ output.mkdir(parents=True)
+ report = dict(
+ scope="selected-v1",
+ stage="FINGERPRINT-REFERENCE",
+ kind="reference-clienthello-only",
+ status="NOT RUN",
+ production_support="UNCHANGED",
+ business_interoperability="NOT TESTED",
+ selection="full" if set(ids) == catalog.keys() else "partial",
+ source=source_identity(),
+ cases=[],
+ cleanup=False,
+ source_unchanged=False,
+ )
+ lab = None
+ try:
+ with exclusive_run(), contextlib.ExitStack() as stack:
+ identity = {}
+ binary = download_mihomo(
+ "linux-arm64", directory=output / "official-mihomo", identity=identity
+ )
+ report["mihomo"] = identity
+ build = run_command(["go", "version", "-m", str(binary)], timeout=10)
+ if build.returncode or not build.cleanup:
+ raise RuntimeError("official binary build identity query failed")
+ (output / "mihomo-build-info.txt").write_bytes(build.stdout)
+ report["utls_build_info"] = [
+ line.strip()
+ for line in build.stdout.decode().splitlines()
+ if "utls" in line or "vcs.revision" in line
+ ]
+ if not any(
+ "github.com/metacubex/utls\tv1.8.7\t" in line
+ for line in report["utls_build_info"]
+ ):
+ raise RuntimeError(
+ "reference uTLS revision changed; recheck selected template mapping"
+ )
+ root = Path(
+ stack.enter_context(
+ tempfile.TemporaryDirectory(prefix="private-", dir=output)
+ )
+ )
+ observer_root, client_root = root / "observer", root / "client"
+ observer_root.mkdir()
+ client_root.mkdir()
+ certificates(observer_root)
+ shutil.copy2(
+ Path(__file__).with_name("container_tls_observer.py"),
+ observer_root / "observer.py",
+ )
+ shutil.copy2(binary, client_root / "mihomo")
+ lab = ContainerLab(report.setdefault("isolation", {}), mtu=1500)
+ observer = lab.start(
+ stack,
+ observer_root,
+ "fingerprint-reference-observer",
+ [
+ "env",
+ "VCORE_ISOLATED_TLS_OBSERVER=1",
+ "python",
+ "-B",
+ "-u",
+ "/data/fixture/observer.py",
+ ],
+ )
+ observer.release()
+ for port in sorted(set(PORTS.values())):
+ observer.wait_tcp(port)
+ secret = secrets.token_hex(24)
+ nodes = {
+ _name(catalog[case]): _node(catalog[case], observer.ipv4)
+ for case in ids
+ }
+ config = dict(
+ proxies=list(nodes.values()),
+ rules=["MATCH,REJECT"],
+ secret=secret,
+ **{"log-level": "warning", "external-controller": "0.0.0.0:25000"},
+ )
+ (client_root / "config.json").write_text(json.dumps(config))
+ client = lab.start(
+ stack,
+ client_root,
+ "fingerprint-reference-mihomo",
+ [
+ "/data/fixture/mihomo",
+ "-d",
+ "/data/mihomo",
+ "-f",
+ "/data/fixture/config.json",
+ ],
+ )
+
+ def retain_logs():
+ for role, peer in (("observer", observer), ("client", client)):
+ if peer.log.exists():
+ text = peer.log.read_text(errors="replace")[-16384:]
+ for value in (secret, observer.ipv4, client.ipv4):
+ text = text.replace(value, "")
+ (output / f"{role}.log").write_text(redact(text))
+
+ stack.callback(retain_logs)
+ identity["version"] = command(
+ "exec", client.name, "/data/fixture/mihomo", "-v"
+ ).strip()
+ digest = command(
+ "exec", client.name, "sha256sum", "/data/fixture/mihomo"
+ ).split()[0]
+ if digest != identity["binary_sha256"]:
+ raise RuntimeError("container official binary identity mismatch")
+ report["observer_tls"] = command(
+ "exec",
+ observer.name,
+ "python",
+ "-c",
+ "import ssl; print(ssl.OPENSSL_VERSION)",
+ ).strip()
+ client.release()
+ client.wait_tcp(25000)
+ observed_count = 0
+ for case_id in ids:
+ case = catalog[case_id]
+ row = dict(case, status="NOT RUN", observations=[])
+ report["cases"].append(row)
+ row["controller"] = _probe(client.ipv4, case, observer.ipv4, secret)
+ deadline = time.monotonic() + 6
+ while True:
+ events = _events(observer, observed_count)
+ if events or time.monotonic() >= deadline:
+ break
+ time.sleep(0.05)
+ if not 1 <= len(events) <= 4:
+ raise RuntimeError(
+ f"reference observation count mismatch: {case_id}"
+ )
+ observed_count += len(events)
+ expected = (
+ "tls-handshake-complete"
+ if case["context"] in {"tls12", "tls13"}
+ else "captured-only"
+ )
+ for event in events:
+ row["observations"].append(event)
+ if "client_hello_b64" not in event:
+ raise RuntimeError(
+ f"reference observer did not capture a hello: {case_id}"
+ )
+ hello = parse_client_hello(
+ base64.b64decode(event["client_hello_b64"], validate=True)
+ )
+ event["parsed"] = hello
+ sni = next(
+ (e["names"] for e in hello["extensions"] if e["type"] == 0), []
+ )
+ if (
+ event["status"] != expected
+ or event["port"] != PORTS[case["context"]]
+ or sni != [dict(type=0, name=case["sni"])]
+ ):
+ raise RuntimeError(
+ f"reference TLS observation mismatch: {case_id}"
+ )
+ row["status"] = "CAPTURED"
+ print(
+ json.dumps(
+ dict(
+ case_id=case_id,
+ status=row["status"],
+ observations=len(events),
+ )
+ ),
+ flush=True,
+ )
+ client.ensure_alive()
+ observer.ensure_alive()
+ report["status"] = "CAPTURED"
+ except BaseException as error:
+ report["status"] = "FAIL"
+ report["error"] = redact(f"{type(error).__name__}: {error}")
+ raise
+ finally:
+ report["source_after"] = source_identity()
+ report["source_unchanged"] = report["source_after"] == report["source"]
+ if lab is not None:
+ report["cleanup"] = not any(
+ item["configuration"].get("labels", {}).get("vcore-run") == lab.run_id
+ for item in listing()
+ ) and all(peer.get("joined") for peer in report["isolation"]["peers"])
+ if report["status"] == "CAPTURED" and not (
+ report["source_unchanged"] and report["cleanup"]
+ ):
+ report["status"] = "FAIL"
+ (output / "reference-results.json").write_text(
+ json.dumps(report, indent=2) + "\n"
+ )
+ print(
+ json.dumps(
+ {key: report[key] for key in ("status", "cleanup", "source_unchanged")}
+ ),
+ flush=True,
+ )
+ return 0 if report["status"] == "CAPTURED" else 1
+
+
+def main(argv=None):
+ parser = argparse.ArgumentParser(description=__doc__)
+ mode = parser.add_mutually_exclusive_group(required=True)
+ mode.add_argument("--list", action="store_true")
+ mode.add_argument("--run-dir", type=Path)
+ mode.add_argument("--check-run", type=Path)
+ parser.add_argument("--case", action="append")
+ args = parser.parse_args(argv)
+ if args.check_run:
+ if args.case:
+ parser.error("--case requires --run-dir")
+ report = args.check_run / "reference-results.json"
+ if report.stat().st_size > 8 * 1024 * 1024:
+ raise ValueError("reference report size limit")
+ print(
+ json.dumps(check_reference_report(json.loads(report.read_text())), indent=2)
+ )
+ return 0
+ if args.list:
+ if args.case:
+ parser.error("--case requires --run-dir")
+ print(json.dumps(reference_cases(), indent=2))
+ return 0
+
+ def stop_signal(_signum, _frame):
+ raise KeyboardInterrupt()
+
+ previous = signal.signal(signal.SIGTERM, stop_signal)
+ try:
+ return run_reference(args.run_dir, args.case)
+ finally:
+ signal.signal(signal.SIGTERM, previous)
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/src/vcore_scripts/protocol_fingerprint_shape.py b/scripts/src/vcore_scripts/protocol_fingerprint_shape.py
new file mode 100644
index 0000000..af053a1
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_fingerprint_shape.py
@@ -0,0 +1,259 @@
+"""Public-config TLS wire checks over memory IO; no network observer."""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import copy
+import io
+import json
+import os
+from pathlib import Path
+
+from .builds import CORE_DIR
+from .container_tls_observer import capture_client_hello
+from .protocol_fingerprint_reference import PROFILES, SNIS, TEMPLATES, _reference_shape
+from .protocol_inputs import redact, same_source, source_identity
+from .protocol_peers import run_command
+from .tls_client_hello import parse_client_hello, validate_capture
+
+CONTEXTS = ("tcp", "ws", "grpc", "reality", "vision", "xhttp-h1", "xhttp-h2")
+
+
+def expected_shape(sample, context):
+ """Transform an independent baseline only for documented caller policies."""
+ case = dict(template=sample["template"], sni=SNIS[0], context=sample["context"])
+ shape = _reference_shape(validate_capture(sample), case)
+ tls13 = context in {"vision", "xhttp-h1", "xhttp-h2"}
+ if tls13:
+ # Standard Vision/XHTTP require TLS1.3 before authentication. These
+ # TLS1.2-only fields are omitted by native version policy, not hidden
+ # from actual captures. REALITY instead enforces TLS1.3 natively while
+ # retaining the browser offer, exactly as the reference does.
+ shape["ciphers"] = [
+ c for c in shape["ciphers"] if c in {"GREASE", 4865, 4866, 4867}
+ ]
+ shape["extensions"] = [
+ e for e in shape["extensions"] if e["type"] not in {11, 23, 35, 65281}
+ ]
+ if context in {"ws", "xhttp-h1"}:
+ shape["extensions"] = [
+ e for e in shape["extensions"] if e["type"] not in {17513, 17613}
+ ]
+ for extension in shape["extensions"]:
+ if extension["type"] == 43:
+ extension["values"] = [
+ v
+ for v in extension["values"]
+ if v == "GREASE" or v >= (772 if tls13 else 771)
+ ]
+ extension["bytes"] = 1 + 2 * len(extension["values"])
+ return shape
+
+
+def check_captures(rows):
+ wanted = {
+ (p, c, s, a) for p in PROFILES for c in CONTEXTS for s in SNIS for a in range(2)
+ }
+ actual = [(r["profile"], r["context"], r["sni"], r["attempt"]) for r in rows]
+ if len(actual) != len(wanted) or set(actual) != wanted:
+ raise ValueError("incomplete or duplicate public-config wire matrix")
+ samples = json.loads(
+ (CORE_DIR / "tests/fingerprints/mihomo-selected-v1.json").read_text()
+ )["samples"]
+ baselines = {(s["profile"], s["context"]): s for s in samples}
+ results = []
+ for row in rows:
+ profile, context = row["profile"], row["context"]
+ canonical = {"firefox120": "firefox", "safari16": "safari"}.get(
+ profile, profile
+ )
+ reference = baselines[(canonical, "reality" if context == "reality" else "tcp")]
+ encoded = row["records_b64"]
+ if len(encoded) > 128 * 1024:
+ raise ValueError("wire capture size limit")
+ wire = base64.b64decode(encoded, validate=True)
+ records, raw, layout = capture_client_hello(io.BytesIO(wire).read)
+ if records != wire or any(
+ r["type"] != 22 or r["version"] != 769 for r in layout
+ ):
+ raise ValueError("unexpected initial TLS record envelope")
+ hello = parse_client_hello(raw)
+ alpn = (
+ ["http/1.1"]
+ if context in {"ws", "xhttp-h1"}
+ else ["h2"]
+ if context == "xhttp-h2"
+ else ["h2", "http/1.1"]
+ )
+ shape = _reference_shape(
+ hello, dict(row, template=TEMPLATES[profile]), expected_alpn=alpn
+ )
+ expected = expected_shape(reference, context)
+ if shape != expected:
+ differences = {
+ k: dict(expected=expected.get(k), observed=shape.get(k))
+ for k in expected.keys() | shape.keys()
+ if expected.get(k) != shape.get(k)
+ }
+ raise ValueError(
+ f"{profile}/{context}/{len(row['sni'])}/{row['attempt']}: "
+ f"{json.dumps(differences)}"
+ )
+ results.append(
+ dict(
+ copy.deepcopy(row),
+ client_hello_b64=base64.b64encode(raw).decode(),
+ records=layout,
+ parsed=hello,
+ status="SHAPE VERIFIED",
+ )
+ )
+ return results
+
+
+def check_warm_captures(rows):
+ wanted = {
+ (p, v, phase)
+ for p in ("chrome", "chrome120", "firefox", "safari")
+ for v in ("TLSv1_2", "TLSv1_3")
+ for phase in ("cold", "warm", "after-hint")
+ }
+ actual = [(r["profile"], r["version"], r["phase"]) for r in rows]
+ if len(actual) != len(wanted) or set(actual) != wanted:
+ raise ValueError("incomplete or duplicate warm/expiry matrix")
+ samples = json.loads(
+ (CORE_DIR / "tests/fingerprints/mihomo-selected-v1.json").read_text()
+ )["samples"]
+ baselines = {s["profile"]: s for s in samples if s["context"] == "tcp"}
+ results = []
+ for row in rows:
+ profile, version, phase = row["profile"], row["version"], row["phase"]
+ stateful_id = profile == "safari" and version == "TLSv1_2"
+ resumed = phase == "warm" or (phase == "after-hint" and stateful_id)
+ if row["resumed"] != resumed:
+ raise ValueError("unexpected real peer resumption/expiry outcome")
+ wire = base64.b64decode(row["records_b64"], validate=True)
+ records, raw, layout = capture_client_hello(io.BytesIO(wire).read)
+ if wire[len(records) :] not in (b"", b"\x14\x03\x03\x00\x01\x01"):
+ raise ValueError("unexpected warm first flight beyond ClientHello/CCS")
+ hello = parse_client_hello(raw)
+ shape = _reference_shape(
+ hello,
+ dict(template=TEMPLATES[profile], sni="fixture.invalid", context="tcp"),
+ allow_psk=True,
+ )
+ expected = expected_shape(baselines[profile], "tcp")
+ if resumed and not stateful_id:
+ length = row["prior_ticket_bytes"]
+ if not isinstance(length, int) or not 1 <= length <= 4096:
+ raise ValueError("independent peer did not issue a bounded ticket")
+ if version == "TLSv1_3":
+ expected["extensions"].append(
+ dict(type=41, bytes=length + 43, identities=[length], binders=[32])
+ )
+ else:
+ ticket = next(e for e in expected["extensions"] if e["type"] == 35)
+ ticket.update(bytes=length, ticket_bytes=length)
+ if shape != expected:
+ differences = {
+ k: dict(expected=expected.get(k), observed=shape.get(k))
+ for k in expected.keys() | shape.keys()
+ if expected.get(k) != shape.get(k)
+ }
+ raise ValueError(
+ f"warm {profile}/{version}/{phase}: {json.dumps(differences)}"
+ )
+ results.append(
+ dict(
+ row,
+ records_b64=base64.b64encode(records).decode(),
+ client_hello_b64=base64.b64encode(raw).decode(),
+ records=layout,
+ parsed=hello,
+ status="SHAPE VERIFIED",
+ )
+ )
+ return results
+
+
+def run(output):
+ if output.parent != CORE_DIR / "target/interop/runs":
+ raise ValueError("use a fresh directory directly under target/interop/runs")
+ output.mkdir(exist_ok=False)
+ report = dict(
+ stage="FINGERPRINT-WIRE",
+ scope="memory-clienthello-structure",
+ source=source_identity(),
+ status="NOT RUN",
+ )
+ try:
+ result = run_command(
+ [
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ "fingerprint_capture",
+ "--",
+ "--nocapture",
+ ],
+ timeout=180,
+ env=dict(
+ os.environ, VCORE_FINGERPRINT_CAPTURE=str(output / "captures.json")
+ ),
+ )
+ (output / "command.log").write_text(
+ redact(result.stdout.decode(errors="replace"))
+ )
+ report["cleanup"] = result.cleanup
+ if result.returncode or not result.cleanup:
+ raise RuntimeError("memory capture command failed")
+ report["cases"] = check_captures(
+ json.loads((output / "captures.json").read_text())
+ )
+ warm = run_command(
+ [
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--lib",
+ "security::tls::tests::named_wire",
+ "--",
+ "--nocapture",
+ ],
+ timeout=180,
+ env=dict(
+ os.environ, VCORE_FINGERPRINT_WARM_CAPTURE=str(output / "warm.json")
+ ),
+ )
+ (output / "warm-command.log").write_text(
+ redact(warm.stdout.decode(errors="replace"))
+ )
+ report["cleanup"] = report["cleanup"] and warm.cleanup
+ if warm.returncode or not warm.cleanup:
+ raise RuntimeError("warm/expiry/version gate failed")
+ report["warm_cases"] = check_warm_captures(
+ json.loads((output / "warm.json").read_text())
+ )
+ report["status"] = "PASS"
+ except Exception as error:
+ report.update(status="FAIL", error=redact(str(error)))
+ finally:
+ report["source_after"] = source_identity()
+ report["source_unchanged"] = same_source(
+ report["source"], report["source_after"]
+ )
+ if not report["source_unchanged"]:
+ report["status"] = "FAIL"
+ (output / "shape-results.json").write_text(json.dumps(report, indent=2) + "\n")
+ print(report["status"], report.get("error", ""))
+ return 0 if report["status"] == "PASS" else 1
+
+
+if __name__ == "__main__":
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("output", type=Path)
+ raise SystemExit(run(parser.parse_args().output.resolve()))
diff --git a/scripts/src/vcore_scripts/protocol_fixtures.py b/scripts/src/vcore_scripts/protocol_fixtures.py
new file mode 100644
index 0000000..d280ba7
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_fixtures.py
@@ -0,0 +1,181 @@
+"""Shared synthetic certificates and peer configuration; never starts a listener."""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+from .protocol_peers import run_command
+
+
+def certificates(directory: Path):
+ cert, key = directory / "cert.pem", directory / "key.pem"
+ generated = run_command(
+ [
+ "openssl",
+ "req",
+ "-x509",
+ "-newkey",
+ "rsa:2048",
+ "-nodes",
+ "-days",
+ "2",
+ "-subj",
+ "/CN=localhost",
+ "-addext",
+ "subjectAltName=DNS:localhost",
+ "-keyout",
+ str(key),
+ "-out",
+ str(cert),
+ ],
+ timeout=20,
+ limit=65536,
+ )
+ der = run_command(
+ ["openssl", "x509", "-in", str(cert), "-outform", "DER"],
+ timeout=10,
+ limit=65536,
+ )
+ if (
+ generated.returncode != 0
+ or der.returncode != 0
+ or not generated.cleanup
+ or not der.cleanup
+ ):
+ raise RuntimeError("synthetic certificate generation failed")
+ return cert, key, hashlib.sha256(der.stdout).hexdigest()
+
+
+def certificate_chain(directory):
+ """Owned synthetic CA + leaf; root pin still verifies the leaf name."""
+ root = directory / "root.pem"
+ root_key = directory / "root-key.pem"
+ key = directory / "key.pem"
+ csr = directory / "leaf.csr"
+ cert = directory / "cert.pem"
+ extensions = directory / "extensions.cnf"
+ extensions.write_text(
+ "basicConstraints=critical,CA:FALSE\nkeyUsage=critical,digitalSignature,keyEncipherment\nextendedKeyUsage=serverAuth\nsubjectAltName=DNS:localhost\n"
+ )
+ commands = [
+ [
+ "openssl",
+ "req",
+ "-x509",
+ "-newkey",
+ "rsa:2048",
+ "-nodes",
+ "-days",
+ "2",
+ "-subj",
+ "/CN=trojan-root",
+ "-addext",
+ "basicConstraints=critical,CA:TRUE",
+ "-keyout",
+ str(root_key),
+ "-out",
+ str(root),
+ ],
+ [
+ "openssl",
+ "req",
+ "-new",
+ "-newkey",
+ "rsa:2048",
+ "-nodes",
+ "-subj",
+ "/CN=localhost",
+ "-keyout",
+ str(key),
+ "-out",
+ str(csr),
+ ],
+ [
+ "openssl",
+ "x509",
+ "-req",
+ "-in",
+ str(csr),
+ "-CA",
+ str(root),
+ "-CAkey",
+ str(root_key),
+ "-set_serial",
+ "2",
+ "-days",
+ "2",
+ "-extfile",
+ str(extensions),
+ "-out",
+ str(cert),
+ ],
+ ["openssl", "x509", "-in", str(root), "-outform", "DER"],
+ ]
+ for command in commands:
+ result = run_command(command, timeout=20, limit=65536)
+ if result.returncode or not result.cleanup:
+ raise RuntimeError("synthetic chain generation failed")
+ cert.write_bytes(cert.read_bytes() + root.read_bytes())
+ return cert, key, hashlib.sha256(result.stdout).hexdigest()
+
+
+def trojan_peer_config(kind, mode, port, password, cert, key):
+ host = "::1" if mode.endswith("-ipv6") else "127.0.0.1"
+ mode = mode.removesuffix("-ipv6").removesuffix("-ca")
+ if kind == "M":
+ listener = {
+ "name": "trojan",
+ "type": "trojan",
+ "listen": host,
+ "port": port,
+ "users": [{"username": "fixture", "password": password}],
+ "certificate": str(cert),
+ "private-key": str(key),
+ }
+ if mode.startswith("ws"):
+ listener["ws-path"] = "cover.example/trojan-ws"
+ if mode.startswith("grpc"):
+ listener["grpc-service-name"] = "trojan-grpc"
+ if mode == "ws-alpn":
+ listener["grpc-service-name"] = "unrelated-service"
+ return {
+ "mode": "rule",
+ "log-level": "silent",
+ "ipv6": True,
+ "hosts": {"vcore-fixture.test": "127.0.0.1"},
+ "listeners": [listener],
+ "rules": ["MATCH,DIRECT"],
+ }
+ stream = {
+ "network": "tcp",
+ "security": "tls",
+ "tlsSettings": {
+ "certificates": [{"certificateFile": str(cert), "keyFile": str(key)}]
+ },
+ }
+ if mode.startswith("ws"):
+ stream.update(network="ws", wsSettings={"path": "/trojan-ws/"})
+ stream["tlsSettings"]["alpn"] = ["http/1.1"]
+ if kind == "V2":
+ stream["wsSettings"].update(
+ maxEarlyData=2048,
+ earlyDataHeaderName="x-vcore-ed" if mode == "ws-header" else "",
+ )
+ if mode == "grpc":
+ stream.update(network="grpc", grpcSettings={"serviceName": "trojan-grpc"})
+ stream["tlsSettings"]["alpn"] = ["h2"]
+ return {
+ "log": {"loglevel": "none"},
+ "dns": {"hosts": {"vcore-fixture.test": "127.0.0.1"}},
+ "inbounds": [
+ {
+ "listen": "127.0.0.1",
+ "port": port,
+ "protocol": "trojan",
+ "settings": {"clients": [{"password": password}]},
+ "streamSettings": stream,
+ }
+ ],
+ "outbounds": [{"protocol": "freedom", "settings": {"domainStrategy": "UseIP"}}],
+ }
diff --git a/scripts/src/vcore_scripts/protocol_harness.py b/scripts/src/vcore_scripts/protocol_harness.py
new file mode 100644
index 0000000..31eb25a
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_harness.py
@@ -0,0 +1,649 @@
+"""Unified foundation and implemented protocol-consumer acceptance runner."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import signal
+import sys
+import tempfile
+import time
+from datetime import UTC, datetime
+from pathlib import Path
+
+from .builds import CORE_DIR
+from .mihomo import _run_mihomo_interop
+from .mihomo_isolation import exclusive_run
+from .protocol_catalogs import CATALOG_DIR, check_protocol_catalogs
+from .protocol_evidence import (
+ check_limit_references,
+ check_run,
+ idle_resources,
+ load_manifest,
+ new_result,
+ read_events,
+ read_json,
+ rust_results,
+ select_cases,
+ validate_results,
+)
+from .protocol_inputs import redact, run_identity, sha256, source_identity
+from .protocol_peers import run_command
+from .protocol_preflight import preflight
+from .protocol_streams import run_streams
+
+
+@contextlib.contextmanager
+def deadline(seconds: float):
+ if not hasattr(signal, "SIGALRM"):
+ raise RuntimeError("whole-suite watchdog requires a supported Unix test host")
+ previous = signal.getsignal(signal.SIGALRM)
+
+ def expired(*_):
+ raise TimeoutError("protocol suite deadline expired")
+
+ signal.signal(signal.SIGALRM, expired)
+ previous_timer = signal.getitimer(signal.ITIMER_REAL)
+ started = time.monotonic()
+ signal.setitimer(
+ signal.ITIMER_REAL,
+ min(seconds, previous_timer[0]) if previous_timer[0] > 0 else seconds,
+ )
+ try:
+ yield
+ finally:
+ remaining = (
+ max(0.001, previous_timer[0] - (time.monotonic() - started))
+ if previous_timer[0] > 0
+ else 0
+ )
+ signal.setitimer(signal.ITIMER_REAL, remaining, previous_timer[1])
+ signal.signal(signal.SIGALRM, previous)
+
+
+def _events(path: Path) -> list[dict]:
+ if not path.exists():
+ return []
+ return read_events(path)
+
+
+def _command(
+ run,
+ output: Path,
+ name: str,
+ command: list[str],
+ seconds: int,
+ *,
+ events: Path | None = None,
+):
+ env = dict(os.environ)
+ env.pop("VCORE_CASE_EVENTS", None)
+ if events:
+ env["VCORE_CASE_EVENTS"] = str(events)
+ print(f"{run.get('stage', 'FOUNDATIONS')}: {name}", flush=True)
+ result = run_command(
+ command, cwd=CORE_DIR, env=env, timeout=seconds, limit=4 * 1024 * 1024
+ )
+ log = output / f"{name}.log"
+ log.write_text(redact(result.stdout.decode("utf-8", errors="replace")))
+ run["commands"].append(
+ {
+ "name": name,
+ "command": [redact(str(part)) for part in command],
+ "exit_code": result.returncode,
+ "seconds": result.seconds,
+ "cleanup": result.cleanup,
+ "reason": result.reason,
+ "log": log.name,
+ }
+ )
+ return result
+
+
+def _features(case, run, output):
+ started = time.monotonic()
+ results = []
+ names = [
+ None,
+ "outbound-trojan",
+ "outbound-vmess",
+ "outbound-hysteria2",
+ "stream-transport",
+ "quic-transport",
+ ]
+ for name in names:
+ command = ["cargo", "check", "--locked", "--no-default-features", "--lib"]
+ if name:
+ command.extend(["--features", name])
+ results.append(
+ _command(
+ run,
+ output,
+ "feature-" + (name or "minimal"),
+ command,
+ max(1, int(case["timeout_seconds"] - (time.monotonic() - started))),
+ )
+ )
+ results.append(
+ _command(
+ run,
+ output,
+ "feature-default",
+ ["cargo", "test", "--locked", "--test", "feature_foundations"],
+ max(1, int(case["timeout_seconds"] - (time.monotonic() - started))),
+ )
+ )
+ cargo = __import__("tomllib").loads((CORE_DIR / "Cargo.toml").read_text())
+ for name in names[1:]:
+ pending = [name]
+ enabled = set()
+ while pending:
+ item = pending.pop()
+ if item not in enabled:
+ enabled.add(item)
+ pending.extend(cargo["features"].get(item, []))
+ if enabled & {"outbound-vless", "tun"}:
+ raise RuntimeError(
+ "foundation feature silently enables an old protocol or TUN"
+ )
+ passed = all(item.returncode == 0 and item.cleanup for item in results)
+ result = new_result(case)
+ result.update(
+ status="PASS" if passed else "FAIL",
+ assertions=dict.fromkeys(case["expected_observation"], passed),
+ evidence=case["required_evidence"] if passed else [],
+ cleanup=all(item.cleanup for item in results),
+ command_exit_code=0 if passed else 1,
+ )
+ return result
+
+
+SCRIPT_OBSERVATIONS = {
+ "offline-success": (
+ "test_protocol_peers.OwnedPeerTest."
+ "test_success_is_bounded_and_records_exit_and_cleanup"
+ ),
+ "missing-duplicate-unknown-case": (
+ "test_protocol_evidence.ProtocolEvidenceTest."
+ "test_missing_duplicate_unknown_and_empty_required_cases_fail"
+ ),
+ "download-failure": (
+ "test_native_release.NativeReleaseTest."
+ "test_failed_download_never_uses_old_binary_or_leaks_network_details"
+ ),
+ "timeout": (
+ "test_protocol_peers.OwnedPeerTest."
+ "test_timeout_and_output_overflow_fail_and_join"
+ ),
+ "sigint": (
+ "test_protocol_peers.OwnedPeerTest."
+ "test_real_sigint_joins_nested_peer_without_stopping_unrelated_peer"
+ ),
+ "partial-start": (
+ "test_protocol_peers.OwnedPeerTest."
+ "test_partial_start_and_permission_failure_do_not_leave_a_process"
+ ),
+ "permission": (
+ "test_protocol_peers.OwnedPeerTest."
+ "test_partial_start_and_permission_failure_do_not_leave_a_process"
+ ),
+ "peer-exit": ("test_protocol_peers.OwnedPeerTest.test_peer_exit_is_not_readiness"),
+ "cleanup-failure": (
+ "test_protocol_peers.OwnedPeerTest.test_cleanup_failure_is_explicit"
+ ),
+ "redaction": (
+ "test_native_release.NativeReleaseTest."
+ "test_failed_download_never_uses_old_binary_or_leaks_network_details"
+ ),
+}
+
+
+def _scripts(case, run, output):
+ path = output / "script-tests.json"
+ command = _command(
+ run,
+ output,
+ "offline-scripts",
+ [sys.executable, "-m", "vcore_scripts.protocol_script_tests", str(path)],
+ case["timeout_seconds"],
+ )
+ data = read_json(path)
+ tests = {entry["test"]: entry["status"] for entry in data["cases"]}
+ assertions = {
+ name: tests.get(identifier) == "PASS"
+ for name, identifier in SCRIPT_OBSERVATIONS.items()
+ }
+ passed = (
+ command.returncode == 0
+ and all(assertions.values())
+ and len(tests) == len(data["cases"]) == data["tests_run"]
+ )
+ result = new_result(case)
+ result.update(
+ status="PASS" if passed else "FAIL",
+ assertions=assertions,
+ evidence=case["required_evidence"] if passed else [],
+ cleanup=command.cleanup,
+ command_exit_code=command.returncode,
+ )
+ return result
+
+
+def _legacy(case, run, output, artifacts):
+ result = new_result(case)
+ if "M" not in artifacts or "M-container" not in artifacts:
+ result.update(
+ status="BLOCKED",
+ reason="M native/container prerequisites unavailable",
+ cleanup=True,
+ )
+ return result
+ path = output / "legacy-events.jsonl"
+ previous = os.environ.get("VCORE_CASE_EVENTS")
+ os.environ["VCORE_CASE_EVENTS"] = str(path)
+ started = time.monotonic()
+ code = 1
+ cleaned = False
+ try:
+ # The existing orchestrator owns exact peers/containers through ExitStack.
+ # SIGINT/timeout unwinds it in this process, not by orphaning a child CLI.
+ with (
+ (output / "legacy.log").open("w") as log,
+ contextlib.redirect_stdout(log),
+ deadline(case["timeout_seconds"]),
+ ):
+ _run_mihomo_interop(
+ artifacts["M"].binary,
+ extended=True,
+ soak_seconds=0,
+ container_binary=artifacts["M-container"].binary,
+ )
+ code = 0
+ cleaned = True
+ except Exception as error:
+ result.update(status="FAIL", reason=type(error).__name__)
+ finally:
+ if previous is None:
+ os.environ.pop("VCORE_CASE_EVENTS", None)
+ else:
+ os.environ["VCORE_CASE_EVENTS"] = previous
+ run["commands"].append(
+ {
+ "name": "legacy-mihomo",
+ "command": ["check", "mihomo-interop", "--container", "--extended"],
+ "exit_code": code,
+ "seconds": round(time.monotonic() - started, 3),
+ "cleanup": cleaned,
+ }
+ )
+ if (output / "legacy.log").exists():
+ log = (output / "legacy.log").read_text()
+ (output / "legacy.log").write_text(redact(log))
+ result = rust_results(case, _events(path), code)
+ result["cleanup"] = cleaned
+ if result["status"] == "PASS":
+ result["evidence"] = case["required_evidence"]
+ return result
+
+
+def _native_results(cases, report):
+ actual = {case["case_id"]: case for case in report.get("cases", [])}
+ results = []
+ for case in cases:
+ result = new_result(case)
+ source = actual.get(case["case_id"], {})
+ event = source.get("rust_event", {})
+ assertions = {
+ "server_first": event.get("server_first") is True,
+ "payload_65536": event.get("payload_bytes") == 65536,
+ "trailer_exact": event.get("tail_bytes") == 14,
+ "origin_complete": source.get("origin")
+ == {"finished": True, "accepted": 1, "received": 65536, "failed": False},
+ "protect_once": event.get("protect_calls") == 1,
+ "driver_joined": event.get("driver_joined") is True,
+ "resources_idle": event.get("resources_idle") is True
+ and idle_resources(event.get("resources")),
+ }
+ passed = (
+ source.get("status") == "PASS"
+ and all(assertions.values())
+ and source.get("cleanup", {}).get("joined") is True
+ and report.get("cleanup") is True
+ )
+ if case["peer_kind"] == "M":
+ cleanup = report.get("abnormal_cleanup", {})
+ passed = passed and cleanup == {
+ "passed": True,
+ "kind": "M",
+ "failure_injected": True,
+ "joined": True,
+ "port_rebound": True,
+ }
+ result.update(
+ status="PASS" if passed else source.get("status", "NOT RUN"),
+ assertions=assertions,
+ evidence=case["required_evidence"] if passed else [],
+ cleanup=source.get("cleanup", {}).get("joined") is True
+ and report.get("cleanup") is True,
+ command_exit_code=source.get("command_exit_code"),
+ seconds=source.get("seconds"),
+ )
+ if not passed and result["status"] == "PASS":
+ result["status"] = "FAIL"
+ results.append(result)
+ return results
+
+
+def _execute(selected, run, output, records):
+ rust = [case for case in selected if case["runner"] == "rust"]
+ if rust:
+ path = output / "rust-events.jsonl"
+ result = _command(
+ run,
+ output,
+ "rust-foundations",
+ ["cargo", "test", "--locked", "--all-features", "--all-targets"],
+ max(case["timeout_seconds"] for case in rust),
+ events=path,
+ )
+ events = _events(path)
+ for case in rust:
+ records[case["case_id"]] = rust_results(case, events, result.returncode)
+ records[case["case_id"]]["cleanup"] = result.cleanup
+ kinds = {case["peer_kind"] for case in selected if case["peer_kind"] != "unit"}
+ artifacts, peers = preflight(
+ output / "binaries",
+ kinds,
+ container=any(case["runner"] == "mihomo-legacy" for case in selected),
+ )
+ (output / "peers.json").write_text(json.dumps(peers, indent=2) + "\n")
+ native = [case for case in selected if case["runner"] == "native-stream"]
+ if native:
+ build = _command(
+ run,
+ output,
+ "native-probe-build",
+ [
+ "cargo",
+ "build",
+ "--locked",
+ "--all-features",
+ "--example",
+ "protocol-stream-probe",
+ ],
+ 300,
+ )
+ if build.returncode == 0:
+ report = {}
+ try:
+ report = run_streams(
+ output / "native",
+ [case["case_id"] for case in native],
+ artifacts=artifacts,
+ )
+ except (OSError, ValueError, RuntimeError):
+ if (output / "native/stream-cases.json").exists():
+ report = read_json(output / "native/stream-cases.json")
+ for result in _native_results(native, report):
+ records[result["case_id"]] = result
+ for case in selected:
+ if case["runner"] == "features":
+ records[case["case_id"]] = _features(case, run, output)
+ elif case["runner"] == "scripts":
+ records[case["case_id"]] = _scripts(case, run, output)
+ elif case["runner"] == "mihomo-legacy":
+ records[case["case_id"]] = _legacy(case, run, output, artifacts)
+
+
+def run_protocol_interop(
+ *,
+ stage: str,
+ identifiers=None,
+ protocol=None,
+ list_only=False,
+ preflight_only=False,
+ run_dir: Path | None = None,
+) -> Path | None:
+ selected = select_cases(
+ load_manifest(), stage=stage, identifiers=identifiers, protocol=protocol
+ )
+ check_limit_references(load_manifest())
+ if list_only:
+ for case in selected:
+ print(
+ f"{case['case_id']}\t{case['substage']}\t{case['peer_kind']}\t{case['protocol']}"
+ )
+ return None
+ if stage in {"FOUNDATIONS", "TROJAN"}:
+ raise RuntimeError(
+ "legacy server orchestration is not fully containerized; "
+ "use check core or a current container suite"
+ )
+ check_protocol_catalogs(CATALOG_DIR)
+ root = CORE_DIR / "target/interop/runs"
+ root.mkdir(parents=True, exist_ok=True)
+ if run_dir is None:
+ output = Path(tempfile.mkdtemp(prefix=f"{stage.lower()}-", dir=root))
+ else:
+ output = run_dir.resolve()
+ if not output.is_relative_to(root.resolve()):
+ raise ValueError(
+ "run directory must be a fresh child of target/interop/runs"
+ )
+ output.mkdir(parents=True, exist_ok=False)
+ print(f"Protocol evidence: {output.relative_to(CORE_DIR.resolve())}", flush=True)
+ (output / "manifest.json").write_text(
+ json.dumps(
+ {
+ "schema_version": 1,
+ "kind": "executable-case-manifest",
+ "cases": load_manifest(),
+ },
+ indent=2,
+ )
+ + "\n"
+ )
+ run = {
+ "schema_version": 1,
+ "stage": stage,
+ "mode": "preflight" if preflight_only else "execute",
+ "selected_cases": [case["case_id"] for case in selected],
+ "commands": [],
+ "cleanup": False,
+ "source_unchanged": False,
+ }
+ records = {case["case_id"]: new_result(case) for case in selected}
+ (output / "peers.json").write_text("[]\n")
+ error = None
+ try:
+ run.update(run_identity(stage, selected, preflight_only))
+ with exclusive_run(), deadline(run["suite_timeout_seconds"]):
+ if preflight_only and stage == "INTEGRATION":
+ from .protocol_integration_acceptance import (
+ preflight as integration_preflight,
+ )
+
+ integration_preflight(output)
+ elif preflight_only and stage == "SECURITY":
+ _, peers = preflight(
+ output / "binaries", {"M", "XR", "V2"}, container=True
+ )
+ (output / "peers.json").write_text(json.dumps(peers, indent=2) + "\n")
+ if any(
+ peer["status"] != "READY" or peer.get("container_status") != "READY"
+ for peer in peers
+ ):
+ raise RuntimeError("SECURITY native prerequisites are BLOCKED")
+ elif preflight_only and stage == "HYSTERIA2":
+ from .protocol_hysteria2_acceptance import preflight as preflight_hy2
+
+ preflight_hy2(output)
+ elif preflight_only and stage == "XHTTP":
+ from .protocol_xhttp_acceptance import preflight as preflight_xhttp
+
+ preflight_xhttp(output)
+ elif preflight_only and stage in {"VMESS", "VLESS"}:
+ if stage == "VMESS":
+ from .protocol_vmess_container import run as preflight_vmess
+ else:
+ from .protocol_vless_container import run as preflight_vmess
+ protocol_name = "vmess" if stage == "VMESS" else "vless"
+
+ native = [
+ case["case_id"]
+ for case in selected
+ if case["runner"] == "native-" + protocol_name
+ ]
+ if preflight_vmess(output / "native", native, preflight_only=True):
+ raise RuntimeError("container protocol preflight failed")
+ peers = read_json(output / f"native/{protocol_name}-results.json")[
+ "peers"
+ ]
+ (output / "peers.json").write_text(json.dumps(peers, indent=2) + "\n")
+ elif preflight_only:
+ _, peers = preflight(
+ output / "binaries", {"M", "V2", "H", "XR"}, container=True
+ )
+ (output / "peers.json").write_text(json.dumps(peers, indent=2) + "\n")
+ if any(
+ peer["status"] != "READY"
+ or peer.get("container_status", "READY") != "READY"
+ for peer in peers
+ ):
+ raise RuntimeError(
+ "some independent peer prerequisites are BLOCKED"
+ )
+ else:
+ if stage == "TROJAN":
+ from .protocol_trojan_acceptance import execute
+
+ execute(selected, run, output, records)
+ elif stage == "VMESS":
+ from .protocol_vmess_acceptance import execute
+
+ execute(selected, run, output, records)
+ elif stage == "VLESS":
+ from .protocol_vless_acceptance import execute
+
+ execute(selected, run, output, records)
+ elif stage == "XHTTP":
+ from .protocol_xhttp_acceptance import execute
+
+ execute(selected, run, output, records)
+ elif stage == "HYSTERIA2":
+ from .protocol_hysteria2_acceptance import execute
+
+ execute(selected, run, output, records)
+ elif stage == "SECURITY":
+ from .protocol_security_acceptance import execute
+
+ execute(selected, run, output, records)
+ elif stage == "INTEGRATION":
+ from .protocol_integration_acceptance import execute
+
+ execute(selected, run, output, records)
+ else:
+ _execute(selected, run, output, records)
+ except BaseException as caught:
+ error = caught
+ run["failure_kind"] = type(caught).__name__
+ finally:
+ results = list(records.values())
+ run["finished_utc"] = datetime.now(UTC).isoformat()
+ try:
+ current = source_identity()
+ run["source_unchanged"] = current == {key: run.get(key) for key in current}
+ except (OSError, RuntimeError, ValueError):
+ run["source_unchanged"] = False
+ run["identity_failure"] = True
+ run["cleanup"] = error is None and (
+ preflight_only or all(result["cleanup"] for result in results)
+ )
+ (output / "cases.json").write_text(json.dumps(results, indent=2) + "\n")
+ resources = []
+ try:
+ for path in output.rglob("*-events.jsonl"):
+ for event in _events(path):
+ if event.get("resources") is not None:
+ resources.append(event)
+ if (output / "native/stream-cases.json").exists():
+ for case in read_json(output / "native/stream-cases.json")["cases"]:
+ if case.get("rust_event", {}).get("resources") is not None:
+ resources.append(
+ {
+ "case_id": case["case_id"],
+ "phase": "after-stop",
+ "resources": case["rust_event"]["resources"],
+ }
+ )
+ except (OSError, ValueError, KeyError, TypeError) as caught:
+ error = error or caught
+ run.update(cleanup=False, failure_kind=type(error).__name__)
+ (output / "resources.jsonl").write_text(
+ "".join(json.dumps(item) + "\n" for item in resources)
+ )
+ status = (
+ "PREFLIGHT"
+ if preflight_only
+ else "PASS"
+ if error is None
+ and run["source_unchanged"]
+ and all(result["status"] == "PASS" for result in results)
+ else "FAIL"
+ )
+ (output / "summary.md").write_text(
+ f"# {stage}: {status}\n\n"
+ + (
+ "Trojan protocol consumer evidence; other protocols remain NOT RUN.\n\n"
+ if stage == "TROJAN"
+ else "VMess protocol consumer evidence with "
+ "container-only servers and origins.\n\n"
+ if stage == "VMESS"
+ else "VLESS consumer evidence with container-only peers; "
+ "XHTTP and security remain separate suites.\n\n"
+ if stage == "VLESS"
+ else "VLESS XHTTP/sing-mux consumer evidence; "
+ "container-only native peers, security remains a separate suite.\n\n"
+ if stage == "XHTTP"
+ else "Hysteria2 consumer evidence with container-only peers; "
+ "native H server limits and platform/device gates remain explicit.\n\n"
+ if stage == "HYSTERIA2"
+ else "Selected VLESS security consumers; static ECH only, "
+ "container-only peers; integration, platforms and devices "
+ "remain separate.\n\n"
+ if stage == "SECURITY"
+ else "Seven-protocol integration; container-only peers. "
+ "Partial selections do not sign off lifecycle or soak gates.\n\n"
+ if stage == "INTEGRATION"
+ else "Foundation-only evidence; "
+ "production protocol field consumers remain NOT RUN.\n\n"
+ )
+ + "\n".join(
+ f"- {result['case_id']}: {result['status']}" for result in results
+ )
+ + "\n"
+ )
+ run["artifacts"] = [
+ {"path": str(path.relative_to(output)), "sha256": sha256(path)}
+ for path in sorted(output.rglob("*"))
+ if path.is_file()
+ and path.suffix in {".json", ".jsonl", ".log", ".md"}
+ and "binaries" not in path.parts
+ and path.name != "run.json"
+ ]
+ (output / "run.json").write_text(json.dumps(run, indent=2) + "\n")
+ if error is not None:
+ raise RuntimeError(
+ f"protocol run incomplete ({type(error).__name__}); "
+ f"see {output.relative_to(CORE_DIR.resolve())}"
+ ) from None
+ if not preflight_only:
+ if not run["source_unchanged"]:
+ raise RuntimeError(
+ "source changed during the run; evidence cannot sign off this input"
+ )
+ validate_results(selected, list(records.values()))
+ if not identifiers and protocol is None:
+ check_run(output, stage)
+ return output
diff --git a/scripts/src/vcore_scripts/protocol_hysteria2.py b/scripts/src/vcore_scripts/protocol_hysteria2.py
new file mode 100644
index 0000000..b1a885a
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_hysteria2.py
@@ -0,0 +1,480 @@
+"""HYSTERIA2 incremental native gates; all servers/origins stay in owned containers."""
+
+from __future__ import annotations
+
+import contextlib
+import copy
+import hashlib
+import json
+import os
+import shutil
+import ssl
+import tempfile
+from pathlib import Path
+
+from .builds import CORE_DIR
+from .mihomo_release import download_mihomo
+from .protocol_containers import ContainerLab, command
+from .protocol_evidence import read_events
+from .protocol_fixtures import certificate_chain, certificates
+from .protocol_hysteria2_catalog import events_pass
+from .protocol_inputs import redact, source_identity
+from .protocol_peers import run_command
+from .protocol_vless_security import client_identities
+
+
+def security_cases(base, identities, leaf_pin):
+ cases = []
+
+ def case(name, changes=None, *, absent=(), success=True):
+ node = copy.deepcopy(base)
+ node.update(changes or {})
+ for field in absent:
+ node.pop(field, None)
+ cases.append(dict(id=name, node=node, success=success))
+
+ case("root-pin")
+ case("leaf-pin", {"fingerprint": leaf_pin})
+ case("root-pin-wrong-name", {"sni": "wrong.fixture.test"}, success=False)
+ case("leaf-pin-is-trust", {"fingerprint": leaf_pin, "sni": "wrong.fixture.test"})
+ case("unknown-ca", absent=("fingerprint",), success=False)
+ case("explicit-skip", {"skip-cert-verify": True}, absent=("fingerprint",))
+ case("wrong-pin", {"fingerprint": "00" * 32}, success=False)
+ case(
+ "skip-does-not-override-pin",
+ {"fingerprint": "00" * 32, "skip-cert-verify": True},
+ success=False,
+ )
+ case("wrong-password", {"password": "not-the-password"}, success=False)
+ case("empty-password", {"port": 23005}, absent=("password",))
+ case("raw-password", {"port": 23006, "password": " untrimmed credential "})
+ case("empty-alpn-default", {"alpn": []})
+ case("custom-alpn", {"port": 23007, "alpn": ["h3-fixture"]})
+ case("wrong-alpn", {"alpn": ["wrong-fixture"]}, success=False)
+ case("mtls-valid", {"port": 23008, **identities["valid"]})
+ case("mtls-absent", {"port": 23008}, success=False)
+ for identity in ("expired", "wrong-ca"):
+ case("mtls-" + identity, {"port": 23008, **identities[identity]}, success=False)
+ obfs = {"obfs": "salamander", "obfs-password": "independent-obfs-fixture"}
+ case("salamander", {"port": 23009, **obfs})
+ case("salamander-client-only", obfs, success=False)
+ case("salamander-server-only", {"port": 23009}, success=False)
+ case(
+ "salamander-wrong-key",
+ {"port": 23009, **obfs, "obfs-password": "wrong-obfs-key"},
+ success=False,
+ )
+ case(
+ "salamander-wrong-auth",
+ {"port": 23009, **obfs, "password": "wrong-auth"},
+ success=False,
+ )
+ return cases
+
+
+def run(output: Path, test="hysteria2_tcp_base", *, obfs=False, supplied=None):
+ if test not in {
+ "hysteria2_tcp_base",
+ "hysteria2_client_first",
+ "hysteria2_udp_base",
+ "native_bandwidth_matrix",
+ "native_mihomo_close_alignment",
+ "native_security_matrix",
+ "native_owned_lifecycle",
+ "native_deadline_and_udp_budget",
+ "runtime::public_lifecycle",
+ "runtime::public_ipv6_and_gates",
+ "runtime::public_entrypoints",
+ "hysteria2::public_udp_boundaries",
+ "hysteria2::public_concrete_upstream",
+ "hysteria2::public_graph_and_hop_snapshot",
+ }:
+ raise ValueError("unknown HYSTERIA2 test")
+ output = output.resolve()
+ output.mkdir(parents=True, exist_ok=False)
+ report = dict(
+ stage="HYSTERIA2",
+ scope="incremental-native",
+ source=source_identity(),
+ status="NOT RUN",
+ isolation={},
+ peers={},
+ cases=[],
+ obfs=obfs,
+ )
+ try:
+ if supplied is None:
+ identity = {}
+ binary = download_mihomo(
+ "linux-arm64", directory=output / "binaries", identity=identity
+ )
+ else:
+ binary, identity = supplied
+ if (
+ hashlib.sha256(binary.read_bytes()).hexdigest()
+ != identity["binary_sha256"]
+ ):
+ raise RuntimeError("supplied native peer identity mismatch")
+ report["peers"]["M"] = identity
+ lab = ContainerLab(report["isolation"], mtu=1500)
+ with tempfile.TemporaryDirectory(prefix="private-", dir=output) as temporary:
+ root = Path(temporary)
+ origin_dir, server_dir = root / "origin", root / "server"
+ origin_dir.mkdir()
+ server_dir.mkdir()
+ shutil.copyfile(
+ Path(__file__).with_name("container_udp_origin.py"),
+ origin_dir / "origin.py",
+ )
+ shutil.copyfile(
+ Path(__file__).with_name("container_close_client.py"),
+ origin_dir / "close.py",
+ )
+ shutil.copy2(binary, server_dir / "peer")
+ cert, key, pin = (
+ certificate_chain if test == "native_security_matrix" else certificates
+ )(server_dir)
+ with contextlib.ExitStack() as stack:
+ origin = lab.start(
+ stack,
+ origin_dir,
+ "hysteria2-origin",
+ [
+ "env",
+ "VCORE_ISOLATED_ORIGIN=1",
+ "python",
+ "-B",
+ "/data/fixture/origin.py",
+ ],
+ )
+ server = lab.start(
+ stack,
+ server_dir,
+ "hysteria2-mihomo",
+ [
+ "/data/fixture/peer",
+ "-d",
+ "/data",
+ "-f",
+ "/data/fixture/config.json",
+ ],
+ )
+ identity["version"] = command(
+ "exec", server.name, "/data/fixture/peer", "-v"
+ ).strip()
+ digest = command(
+ "exec", server.name, "sha256sum", "/data/fixture/peer"
+ ).split()[0]
+ if digest != identity["binary_sha256"]:
+ raise RuntimeError("native peer identity mismatch")
+ upstream = server
+ if test in {
+ "hysteria2::public_concrete_upstream",
+ "hysteria2::public_graph_and_hop_snapshot",
+ }:
+ # A separate native instance prevents its own outer UDP
+ # source tuple from tripping Mihomo's loopback detector.
+ hop_dir = root / "hop"
+ hop_dir.mkdir()
+ shutil.copy2(binary, hop_dir / "peer")
+ (hop_dir / "config.json").write_text(
+ json.dumps(
+ {
+ "socks-port": 23001,
+ "allow-lan": True,
+ "bind-address": "*",
+ "ipv6": True,
+ "log-level": "silent",
+ "rules": ["MATCH,DIRECT"],
+ }
+ )
+ )
+ upstream = lab.start(
+ stack,
+ hop_dir,
+ "hysteria2-hop",
+ [
+ "/data/fixture/peer",
+ "-d",
+ "/data",
+ "-f",
+ "/data/fixture/config.json",
+ ],
+ )
+ upstream.release()
+ upstream.wait_tcp(23001)
+ password = "synthetic-hysteria2-fixture"
+ (server_dir / "config.json").write_text(
+ json.dumps(
+ {
+ "socks-port": 23001,
+ "allow-lan": True,
+ "bind-address": "*",
+ "ipv6": True,
+ "log-level": "silent",
+ "hosts": {"vcore-fixture.test": origin.ipv4},
+ "listeners": [
+ {
+ "name": "hysteria2",
+ "type": "hysteria2",
+ "listen": "::",
+ "port": 23000,
+ "users": {"fixture": password},
+ "certificate": f"/data/fixture/{cert.name}",
+ "private-key": f"/data/fixture/{key.name}",
+ }
+ ],
+ "rules": ["MATCH,DIRECT"],
+ }
+ )
+ )
+ fixture = root / "input.json"
+ bandwidth_peer = None
+ if test == "native_bandwidth_matrix":
+ bandwidth_dir = root / "bandwidth"
+ bandwidth_dir.mkdir()
+ shutil.copyfile(
+ Path(__file__).with_name("container_bandwidth_origin.py"),
+ bandwidth_dir / "origin.py",
+ )
+ bandwidth_peer = lab.start(
+ stack,
+ bandwidth_dir,
+ "hysteria2-bandwidth",
+ [
+ "env",
+ "VCORE_ISOLATED_ORIGIN=1",
+ "python",
+ "-B",
+ "/data/fixture/origin.py",
+ ],
+ )
+ bandwidth_peer.release()
+ bandwidth_peer.wait_tcp(24002)
+ peer_config = json.loads((server_dir / "config.json").read_text())
+ baseline = peer_config["listeners"][0]
+ for port, options in [
+ (23002, {"down": "1 Mbps"}),
+ (23003, {"up": "1 Mbps"}),
+ (23004, {"ignore-client-bandwidth": True}),
+ ]:
+ peer_config["listeners"].append(
+ dict(
+ baseline, name=f"hysteria2-{port}", port=port, **options
+ )
+ )
+ (server_dir / "config.json").write_text(json.dumps(peer_config))
+ fixture.write_text(
+ json.dumps(
+ dict(
+ isolation="containers",
+ origin_control=f"{origin.ipv4}:24000",
+ origin_ipv4=origin.ipv4,
+ origin_ipv6=origin.ipv6,
+ server_ipv6=server.ipv6,
+ data_dir=str(root / "data"),
+ hop=dict(
+ name="hop",
+ type="socks5",
+ server=upstream.ipv4,
+ port=23001,
+ udp=True,
+ ),
+ bandwidth_control=f"{bandwidth_peer.ipv4}:24002"
+ if bandwidth_peer
+ else None,
+ bandwidth_ipv4=bandwidth_peer.ipv4
+ if bandwidth_peer
+ else None,
+ node=dict(
+ name="peer",
+ type="hysteria2",
+ server=server.ipv4,
+ port=23000,
+ password=password,
+ udp=True,
+ sni="localhost",
+ fingerprint=pin,
+ alpn=["h3"],
+ ),
+ )
+ )
+ )
+ if test == "native_security_matrix":
+ identities = client_identities(server_dir)
+ peer_config = json.loads((server_dir / "config.json").read_text())
+ baseline = peer_config["listeners"][0]
+ for port, options in [
+ (23005, {"users": {"fixture": ""}}),
+ (23006, {"users": {"fixture": " untrimmed credential "}}),
+ (23007, {"alpn": ["h3-fixture"]}),
+ (
+ 23008,
+ {
+ "client-auth-type": "require-and-verify",
+ "client-auth-cert": "/data/fixture/root.pem",
+ },
+ ),
+ (
+ 23009,
+ {
+ "obfs": "salamander",
+ "obfs-password": "independent-obfs-fixture",
+ },
+ ),
+ ]:
+ peer_config["listeners"].append(
+ dict(
+ baseline, name=f"hysteria2-{port}", port=port, **options
+ )
+ )
+ (server_dir / "config.json").write_text(json.dumps(peer_config))
+ value = json.loads(fixture.read_text())
+ leaf = (
+ cert.read_text().split("-----END CERTIFICATE-----", 1)[0]
+ + "-----END CERTIFICATE-----\n"
+ )
+ leaf_pin = hashlib.sha256(
+ ssl.PEM_cert_to_DER_cert(leaf)
+ ).hexdigest()
+ value["security"] = security_cases(
+ value["node"], identities, leaf_pin
+ )
+ value["invalid_identities"] = [
+ {
+ "certificate": identities["valid"]["certificate"],
+ "private-key": identities["expired"]["private-key"],
+ },
+ {
+ "certificate": "bad PEM",
+ "private-key": identities["valid"]["private-key"],
+ },
+ ]
+ fixture.write_text(json.dumps(value))
+ if obfs:
+ peer_config = json.loads((server_dir / "config.json").read_text())
+ for listener in peer_config["listeners"]:
+ listener.update(
+ obfs="salamander",
+ **{"obfs-password": "independent-obfs-fixture"},
+ )
+ (server_dir / "config.json").write_text(json.dumps(peer_config))
+ value = json.loads(fixture.read_text())
+ value["node"].update(
+ obfs="salamander",
+ **{"obfs-password": "independent-obfs-fixture"},
+ )
+ fixture.write_text(json.dumps(value))
+ origin.release()
+ server.release()
+ origin.wait_tcp(24000)
+ server.wait_tcp(23001)
+ if test == "native_mihomo_close_alignment":
+ from .protocol_xhttp_fields import close_reference
+
+ value = json.loads(fixture.read_text())
+ value["close_reference"] = close_reference(
+ lab, stack, root, "hy2", value["node"], origin, binary, output
+ )
+ fixture.write_text(json.dumps(value))
+ events = output / f"{test}-events.jsonl"
+ result = run_command(
+ [
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ "hysteria2_native"
+ if test.startswith("native_")
+ else "vless_public",
+ test,
+ "--",
+ "--ignored",
+ "--exact",
+ "--nocapture",
+ ],
+ cwd=CORE_DIR,
+ timeout=600 if test == "native_bandwidth_matrix" else 240,
+ limit=4 * 1024 * 1024,
+ env=dict(
+ os.environ,
+ VCORE_VLESS_INPUT=str(fixture),
+ VCORE_CASE_EVENTS=str(events),
+ VCORE_PROTOCOL_STAGE="HYSTERIA2",
+ VCORE_BANDWIDTH_OBSERVATIONS=str(output / "bandwidth.jsonl"),
+ ),
+ )
+ (output / f"{test}.log").write_text(
+ redact(result.stdout.decode(errors="replace"))
+ )
+ observed = read_events(events) if events.exists() else []
+ passed = (
+ result.returncode == 0
+ and result.cleanup
+ and events_pass(observed, test)
+ )
+ report["cases"].append(
+ dict(
+ case_id=test,
+ status="PASS" if passed else "FAIL",
+ exit_code=result.returncode,
+ seconds=result.seconds,
+ command_cleanup=result.cleanup,
+ command=test_command(test),
+ )
+ )
+ report["status"] = "PASS" if passed else "FAIL"
+ for role, peer in (("origin", origin), ("server", server)):
+ peer.ensure_alive()
+ if peer.log.exists():
+ (output / f"{role}.log").write_text(
+ redact(peer.log.read_text(errors="replace")[-65536:])
+ )
+ except (OSError, RuntimeError, ValueError) as error:
+ report.update(
+ status="FAIL",
+ reason=str(error)
+ if isinstance(error, RuntimeError)
+ else type(error).__name__,
+ )
+ finally:
+ report["cleanup"] = all(
+ peer["joined"] for peer in report["isolation"].get("peers", [])
+ )
+ report["source_unchanged"] = (
+ source_identity()["source_tree_sha256"]
+ == report["source"]["source_tree_sha256"]
+ )
+ if not report["source_unchanged"] or not report["cleanup"]:
+ report["status"] = "FAIL"
+ (output / "report.json").write_text(json.dumps(report, indent=2) + "\n")
+ return report
+
+
+def test_command(test):
+ return [
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ "hysteria2_native" if test.startswith("native_") else "vless_public",
+ test,
+ "--",
+ "--ignored",
+ "--exact",
+ "--nocapture",
+ ]
+
+
+if __name__ == "__main__":
+ import sys
+
+ result = run(
+ Path(sys.argv[1]),
+ sys.argv[2] if len(sys.argv) > 2 else "hysteria2_tcp_base",
+ obfs="--salamander" in sys.argv[3:],
+ )
+ print(json.dumps({key: result[key] for key in ("status", "cleanup", "cases")}))
+ raise SystemExit(0 if result["status"] == "PASS" and result["cleanup"] else 1)
diff --git a/scripts/src/vcore_scripts/protocol_hysteria2_acceptance.py b/scripts/src/vcore_scripts/protocol_hysteria2_acceptance.py
new file mode 100644
index 0000000..b3c1fa1
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_hysteria2_acceptance.py
@@ -0,0 +1,670 @@
+"""Hysteria2 execution and fail-closed reconstruction of persisted evidence."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import sys
+
+from .builds import DEFAULT_FEATURES
+from .protocol_evidence import HEX, new_result, read_events, read_json
+from .protocol_hysteria2_catalog import (
+ CFG,
+ FIELDS,
+ GATES,
+ H3,
+ UNIT,
+ H,
+ M,
+ assertions_pass,
+ definitions,
+ events_pass,
+)
+from .protocol_inputs import redact
+
+
+def commands(identifier):
+ cargo = ["cargo", "test", "--locked", "--all-features"]
+ if identifier in {"HYSTERIA2-CFG", "HYSTERIA2-UNIT", "HYSTERIA2-RELEASE"}:
+ if identifier == "HYSTERIA2-RELEASE":
+ cargo += ["--release"]
+ result = []
+ if identifier != "HYSTERIA2-UNIT":
+ result.append(cargo + ["--test", "hysteria2_config"])
+ if identifier != "HYSTERIA2-CFG":
+ result += [
+ cargo + ["--lib", "outbound::hysteria2::"],
+ cargo
+ + [
+ "--lib",
+ "outbound::connector::tests::authenticated_continuation_keeps_group_choice_but_has_a_new_io_deadline",
+ "--",
+ "--exact",
+ ],
+ cargo + ["--test", "hysteria2_paths"],
+ ]
+ return result
+ if identifier == "HYSTERIA2-REGRESSION":
+ # Every chosen test uses memory IO/config, never a host server.
+ targets = [
+ "feature_foundations",
+ "limit_foundations",
+ "trojan",
+ "trojan_config",
+ "vmess_config",
+ "vless_config",
+ "vless_lifecycle",
+ "xhttp_config",
+ "xhttp_budget",
+ "h2_stream_regression",
+ "stream_foundations",
+ ]
+ return [
+ cargo + sum((["--test", name] for name in targets), []),
+ cargo
+ + [
+ "--test",
+ "quic_datagram_foundations",
+ "pending_send_is_not_restarted_and_stop_cancels_without_waiting_for_writable",
+ "--",
+ "--exact",
+ ],
+ ]
+ if identifier == "HYSTERIA2-QUALITY":
+ from .protocol_vmess_acceptance import commands as previous
+
+ return previous("VMESS-QUALITY")[:7] + [
+ [
+ "cargo",
+ "clippy",
+ "--locked",
+ "--all-features",
+ "--all-targets",
+ "--",
+ "-D",
+ "warnings",
+ ],
+ [
+ "cargo",
+ "test",
+ "--locked",
+ "--manifest-path",
+ "crates/vcore-netstack/Cargo.toml",
+ "--all-targets",
+ ],
+ [
+ "cargo",
+ "clippy",
+ "--locked",
+ "--manifest-path",
+ "crates/vcore-netstack/Cargo.toml",
+ "--all-targets",
+ "--",
+ "-D",
+ "warnings",
+ ],
+ ]
+ if identifier == "HYSTERIA2-PLATFORMS":
+ return [
+ ["vcore-scripts", "build", "apple"],
+ ["vcore-scripts", "build", "android"],
+ ]
+ if identifier == "HYSTERIA2-FEATURES":
+ checks = [
+ ["cargo", "check", "--locked", "--no-default-features", "--lib"]
+ + (["--features", feature] if feature else [])
+ for feature in (
+ "",
+ "outbound-hysteria2",
+ "quic-transport",
+ "outbound-vless",
+ "tun",
+ )
+ ]
+ return checks + [
+ [
+ "cargo",
+ "test",
+ "--locked",
+ "--test",
+ "feature_foundations",
+ "--test",
+ "hysteria2_config",
+ ],
+ [
+ "cargo",
+ "test",
+ "--locked",
+ "--no-default-features",
+ "--test",
+ "hysteria2_config",
+ ],
+ [
+ "cargo",
+ "test",
+ "--locked",
+ "--no-default-features",
+ "--features",
+ "outbound-hysteria2",
+ "--test",
+ "hysteria2_config",
+ ],
+ [
+ "cargo",
+ "build",
+ "--locked",
+ "--release",
+ "--no-default-features",
+ "--features",
+ DEFAULT_FEATURES,
+ "--lib",
+ ],
+ ]
+ if identifier == "HYSTERIA2-SCRIPTS":
+ return [
+ [
+ sys.executable,
+ "-m",
+ "vcore_scripts.protocol_script_tests",
+ "{output}/script-tests.json",
+ ]
+ ]
+ return []
+
+
+def gate_result(case, records, events, script=None):
+ identifier = case["case_id"]
+ good = bool(records) and all(
+ r.get("exit_code") == 0 and r.get("cleanup") is True for r in records
+ )
+ if identifier in {"HYSTERIA2-CFG", "HYSTERIA2-UNIT", "HYSTERIA2-RELEASE"}:
+ expected = {}
+ if identifier != "HYSTERIA2-UNIT":
+ expected.update({("HYSTERIA2-CFG", name): 1 for name in CFG})
+ if identifier != "HYSTERIA2-CFG":
+ expected.update({("HYSTERIA2-UNIT", name): 1 for name in UNIT})
+ good &= assertions_pass(events, expected)
+ if identifier == "HYSTERIA2-SCRIPTS":
+ required = {
+ "test_protocol_hysteria2.Hysteria2AcceptanceTest." + name
+ for name in (
+ "test_catalog_covers_all_fields_and_eight_hop_combinations",
+ "test_partial_unknown_duplicate_and_wrong_suite_events_fail",
+ "test_native_identity_cleanup_or_missing_results_fail",
+ "test_bandwidth_and_hop_counters_cannot_be_forged_as_empty_success",
+ )
+ }
+ samples = (script or {}).get("cases", [])
+ names = [s.get("test") for s in samples]
+ good &= (
+ bool(samples)
+ and len(names) == len(set(names)) == (script or {}).get("tests_run")
+ and required <= set(names)
+ and all(s.get("status") == "PASS" for s in samples)
+ )
+ result = new_result(case)
+ result.update(
+ status="PASS" if good else "FAIL",
+ assertions=dict.fromkeys(case["expected_observation"], bool(good)),
+ evidence=case["required_evidence"] if good else [],
+ command_exit_code=0 if good else 1,
+ cleanup=bool(records) and all(r.get("cleanup") is True for r in records),
+ )
+ return result
+
+
+def bandwidth_pass(samples):
+ expected = [
+ (d, u, down, port, controller)
+ for d in ("U", "D")
+ for u, down, port, controller in (
+ (0, 0, 23000, 0),
+ *(
+ (rate, 100, 23000, rate * 125000) if d == "U" else (0, rate, 23000, 0)
+ for rate in (1, 2)
+ ),
+ (2, 100, 23002, 125000) if d == "U" else (0, 2, 23003, 0),
+ )
+ ] + [("U", 2, 0, 23000, 0), ("U", 2, 2, 23004, 0)]
+ if len(samples) != len(expected):
+ return False
+ for sample, key in zip(samples, expected, strict=True):
+ if (
+ tuple(
+ sample.get(k)
+ for k in (
+ "direction",
+ "up_mbps",
+ "down_mbps",
+ "listener_port",
+ "controller_bps",
+ )
+ )
+ != key
+ ):
+ return False
+ buckets = sample.get("buckets", [])
+ if (
+ len(buckets) != 30
+ or any(type(v) is not int or v < 0 for v in buckets)
+ or sample.get("payload_bps", 0) <= 0
+ or sample["payload_bps"] != sum(buckets) / 30
+ or sample.get("udp_tx_bytes", 0) <= 0
+ or sample.get("udp_rx_bytes", 0) <= 0
+ ):
+ return False
+ for offset in (0, 4):
+ rates = [samples[offset + i]["payload_bps"] for i in range(4)]
+ if (
+ rates[0] < 750000
+ or rates[1] > 125000 * 1.1
+ or rates[2] > 250000 * 1.1
+ or rates[2] < rates[1] * 1.5
+ or rates[3] > 125000 * 1.1
+ ):
+ return False
+ return True
+
+
+def hopping_pass(value):
+ return (
+ value.get("seconds", 0) >= 60
+ and value.get("protected_sockets", 0) >= 9
+ and value.get("tcp_bytes_per_direction", 0) >= 10 * 1024 * 1024
+ and HEX.fullmatch(value.get("tcp_sha256", "")) is not None
+ and value.get("udp_packets") == 1500
+ and value.get("udp_target_kinds") == 3
+ and len(value.get("udp_maximums", [])) == 3
+ and all(1200 < n < 4096 for n in value["udp_maximums"])
+ and value.get("socket_peak") == 2
+ )
+
+
+def native_result(case, report, directory):
+ from .protocol_hysteria2 import test_command
+
+ identifier = case["case_id"]
+ test = M[identifier][0] if identifier in M else H[identifier]["test"]
+ records = report.get("cases", [])
+ events = directory / (
+ f"{test}-events.jsonl" if identifier in M else "hysteria2-events.jsonl"
+ )
+ observed = read_events(events) if events.exists() else []
+ isolation = report.get("isolation", {})
+ peers = isolation.get("peers", [])
+ clean = (
+ report.get("cleanup") is True
+ and bool(peers)
+ and all(p.get("joined") is True and p.get("started") is True for p in peers)
+ )
+ good = (
+ clean
+ and report.get("status") == "PASS"
+ and report.get("source_unchanged") is True
+ and isolation.get("network_mode") == "hostOnly"
+ and isolation.get("host_servers") is False
+ and isolation.get("guest_mtu") == 1500
+ and bool(isolation.get("image_digest"))
+ )
+ good &= (
+ len(records) == 1
+ and all(
+ r.get("case_id") == test
+ and r.get("status") == "PASS"
+ and r.get("exit_code") == 0
+ and r.get("command_cleanup") is True
+ and r.get("command") == test_command(test)
+ for r in records
+ )
+ and events_pass(observed, test)
+ )
+ if identifier in M:
+ good &= report.get("obfs") is M[identifier][1]
+ identity = report.get("peers", {}).get("M", {})
+ project = "MetaCubeX/mihomo"
+ else:
+ identity = report.get("peer", {})
+ project = "HyNetworks/hysteria"
+ good &= (
+ all(
+ report.get(k) is H[identifier][k]
+ for k in ("ipv6", "obfs", "random_interval")
+ )
+ and report.get("auth_connections") == 1
+ )
+ counts = report.get("entry_port_packets", {})
+ good &= (
+ set(counts) == {"p23010", "p23011", "p23012"}
+ and all(type(v) is int and v >= 0 for v in counts.values())
+ and sum(v > 0 for v in counts.values())
+ >= (2 if test == "native_hopping" else 1)
+ )
+ if test == "native_hopping":
+ good &= (directory / "hopping.json").exists() and hopping_pass(
+ read_json(directory / "hopping.json")
+ )
+ good &= (
+ bool(identity.get("version"))
+ and HEX.fullmatch(identity.get("binary_sha256", "")) is not None
+ and identity.get("source_url", "").startswith(
+ f"https://github.com/{project}/releases/"
+ )
+ )
+ if test == "native_bandwidth_matrix":
+ path = directory / "bandwidth.jsonl"
+ good &= path.exists() and bandwidth_pass(read_events(path))
+ if test == "native_mihomo_close_alignment":
+ path = directory / "hy2-close-reference.json"
+ reference = read_json(path) if path.exists() else {}
+ good &= reference == {"tail_hex": "", "terminated": True, "scope": "same-mode"}
+ result = new_result(case)
+ result.update(
+ status="PASS" if good else "FAIL",
+ assertions={test: bool(good)},
+ evidence=case["required_evidence"] if good else [],
+ command_exit_code=0 if good else 1,
+ cleanup=clean,
+ )
+ return result
+
+
+def fields_report(cases, results):
+ status = {r["case_id"]: r["status"] for r in results}
+ rows = []
+ for field in sorted(FIELDS):
+ native = [
+ c["case_id"]
+ for c in cases
+ if field in c["row_ids"] and c["case_id"] in M | H
+ ]
+ good = (
+ status.get("HYSTERIA2-CFG") == "PASS"
+ and bool(native)
+ and all(status.get(i) == "PASS" for i in native)
+ )
+ rows.append(
+ dict(
+ row_id=field,
+ configuration="HYSTERIA2-CFG",
+ behavior_cases=native,
+ status="PASS" if good else "NOT RUN",
+ )
+ )
+ return dict(stage="HYSTERIA2", scope="hysteria2-consumer", fields=rows)
+
+
+def prepare(output, kinds):
+ from .protocol_containers import ContainerLab
+ from .protocol_hysteria2_hop import native_binary, packages
+ from .protocol_xhttp_acceptance import prepare_peers
+
+ supplied = prepare_peers(output, kinds - {"H"})
+ if "H" in kinds:
+ root = output / "binaries/H"
+ root.mkdir(parents=True)
+ binary, identity = native_binary(root)
+ record = {}
+ try:
+ lab = ContainerLab(record, mtu=1500)
+ with contextlib.ExitStack() as stack:
+ apks = packages(lab, stack, root / "apks")
+ supplied["H"] = binary, identity, apks, record["firewall_packages"]
+ finally:
+ (output / "package-preparation.json").write_text(
+ json.dumps(record, indent=2) + "\n"
+ )
+ return supplied
+
+
+def h3_jobs():
+ return {
+ name: [dict(case_id=name, test="public_base")]
+ for name in (
+ "h3-stream-one-headers",
+ "h3-stream-up-headers",
+ "h3-packet-up-headers",
+ )
+ }
+
+
+def h3_result(case, report, directory):
+ from .protocol_xhttp_fields import public_events_pass
+
+ jobs = h3_jobs()
+ records = report.get("cases", [])
+ isolation = report.get("isolation", {})
+ owned = isolation.get("peers", [])
+ good = (
+ report.get("status") == "PASS"
+ and report.get("cleanup") is True
+ and report.get("source_unchanged") is True
+ and {r.get("case_id") for r in records} == set(jobs)
+ and len(records) == len(jobs)
+ and isolation.get("network_mode") == "hostOnly"
+ and isolation.get("host_servers") is False
+ and isolation.get("guest_mtu") == 1500
+ and bool(isolation.get("image_digest"))
+ and bool(owned)
+ and all(p.get("started") is True and p.get("joined") is True for p in owned)
+ and set(report.get("peers", {})) == {"M", "XR"}
+ )
+ for record in records:
+ path = directory / (record["case_id"] + "-events.jsonl")
+ good &= (
+ record.get("exit_code") == 0
+ and record.get("command_cleanup") is True
+ and record.get("status") == "PASS"
+ and record.get("assertion") == "public_base"
+ and record.get("command")
+ == [
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ "vless_public",
+ "public_base",
+ "--",
+ "--exact",
+ "--ignored",
+ "--nocapture",
+ ]
+ and path.exists()
+ and public_events_pass(read_events(path), "public_base")
+ )
+ result = new_result(case)
+ result.update(
+ status="PASS" if good else "FAIL",
+ assertions={case["expected_observation"][0]: bool(good)},
+ evidence=case["required_evidence"] if good else [],
+ command_exit_code=0 if good else 1,
+ cleanup=report.get("cleanup") is True,
+ )
+ return result
+
+
+def execute(cases, run, output, results):
+ from .protocol_harness import _command
+ from .protocol_hysteria2 import run as run_m
+ from .protocol_hysteria2_hop import run as run_h
+
+ supplied = {}
+ try:
+ for case in cases:
+ identifier = case["case_id"]
+ if identifier not in GATES:
+ continue
+ records, events = [], []
+ for index, argv in enumerate(commands(identifier)):
+ argv = [v.replace("{output}", str(output)) for v in argv]
+ name = f"{identifier}-{index}"
+ path = output / f"{name}-events.jsonl"
+ _command(run, output, name, argv, case["timeout_seconds"], events=path)
+ records.append(run["commands"][-1])
+ if path.exists():
+ events += read_events(path)
+ script = (
+ read_json(output / "script-tests.json")
+ if identifier == "HYSTERIA2-SCRIPTS"
+ else None
+ )
+ results[identifier] = gate_result(case, records, events, script)
+ if results[identifier]["status"] != "PASS":
+ raise RuntimeError(f"HYSTERIA2 local gate failed: {identifier}")
+ kinds = {"M" for c in cases if c["case_id"] in M} | {
+ "H" for c in cases if c["case_id"] in H
+ }
+ if any(c["case_id"] == H3 for c in cases):
+ kinds |= {"M", "XR"}
+ supplied = prepare(output, kinds)
+ for case in cases:
+ identifier = case["case_id"]
+ directory = output / identifier
+ if identifier in M:
+ test, obfs, _ = M[identifier]
+ report = run_m(directory, test, obfs=obfs, supplied=supplied["M"])
+ result = native_result(case, report, directory)
+ elif identifier in H:
+ report = run_h(directory, **H[identifier], supplied=supplied["H"])
+ result = native_result(case, report, directory)
+ elif identifier == H3:
+ from .protocol_xhttp_fields import run as run_h3
+
+ jobs = h3_jobs()
+ run_h3(
+ directory,
+ list(jobs),
+ jobs=jobs,
+ supplied={k: supplied[k] for k in ("M", "XR")},
+ )
+ report = read_json(directory / "xhttp-fields-results.json")
+ result = h3_result(case, report, directory)
+ else:
+ continue
+ results[identifier] = result
+ print(f"{identifier}: {result['status']}", flush=True)
+ if result["status"] != "PASS":
+ raise RuntimeError(f"HYSTERIA2 native gate failed: {identifier}")
+ finally:
+ (output / "peers.json").write_text(
+ json.dumps(
+ {kind: artifact[1] for kind, artifact in supplied.items()}, indent=2
+ )
+ + "\n"
+ )
+ (output / "fields.json").write_text(
+ json.dumps(fields_report(cases, list(results.values())), indent=2) + "\n"
+ )
+
+
+def check(run_dir, cases, run, results, peers, paths):
+ if (
+ cases != definitions()
+ or set(peers) != {"M", "H", "XR"}
+ or not {
+ "fields.json",
+ "script-tests.json",
+ "package-preparation.json",
+ }
+ <= set(paths)
+ ):
+ raise ValueError("incomplete HYSTERIA2 stage artifacts or altered manifest")
+ actual = {r["case_id"]: r for r in results}
+ records = run.get("commands", [])
+ expected_names = {
+ f"{c['case_id']}-{i}"
+ for c in cases
+ for i, _ in enumerate(commands(c["case_id"]))
+ }
+ if (
+ len(records) != len(expected_names)
+ or {r.get("name") for r in records} != expected_names
+ ):
+ raise ValueError("missing, duplicate or extra HYSTERIA2 validation command")
+ source = {
+ k: run[k]
+ for k in (
+ "parent_commit",
+ "source_tree_sha256",
+ "dirty_patch_sha256",
+ "lock_sha256",
+ )
+ }
+ for case in cases:
+ identifier = case["case_id"]
+ if identifier in GATES:
+ selected, events = [], []
+ for i, argv in enumerate(commands(identifier)):
+ record = next(r for r in records if r["name"] == f"{identifier}-{i}")
+ if (
+ record["command"]
+ != [redact(v.replace("{output}", str(run_dir))) for v in argv]
+ or record["log"] not in paths
+ ):
+ raise ValueError("HYSTERIA2 validation command/log changed")
+ selected.append(record)
+ path = run_dir / f"{identifier}-{i}-events.jsonl"
+ if path.exists():
+ events += read_events(path)
+ recalculated = gate_result(
+ case,
+ selected,
+ events,
+ read_json(run_dir / "script-tests.json")
+ if identifier == "HYSTERIA2-SCRIPTS"
+ else None,
+ )
+ else:
+ directory = run_dir / identifier
+ report = read_json(
+ directory
+ / ("xhttp-fields-results.json" if identifier == H3 else "report.json")
+ )
+ if report.get("source") != source:
+ raise ValueError("HYSTERIA2 native source differs from stage input")
+ recalculated = (
+ h3_result(case, report, directory)
+ if identifier == H3
+ else native_result(case, report, directory)
+ )
+ if identifier in H:
+ if report.get("peer") != peers.get("H"):
+ raise ValueError("H native identity changed")
+ preparation = read_json(run_dir / "package-preparation.json")
+ if report.get("isolation", {}).get(
+ "firewall_packages"
+ ) != preparation.get("firewall_packages"):
+ raise ValueError("H native firewall package identity changed")
+ elif set(report.get("peers", {})) != (
+ {"M", "XR"} if identifier == H3 else {"M"}
+ ):
+ raise ValueError("missing or extra native peer identity")
+ elif any(
+ identity != peers.get(kind)
+ for kind, identity in report.get("peers", {}).items()
+ ):
+ raise ValueError("native identity changed between reports")
+ if recalculated != actual[identifier] or recalculated["status"] != "PASS":
+ raise ValueError("HYSTERIA2 results differ from structured evidence")
+ preparation = read_json(run_dir / "package-preparation.json")
+ if (
+ not preparation.get("firewall_packages")
+ or not preparation.get("peers")
+ or any(p.get("joined") is not True for p in preparation["peers"])
+ ):
+ raise ValueError("native firewall preparation identity/cleanup missing")
+ fields = fields_report(cases, results)
+ if read_json(run_dir / "fields.json") != fields or any(
+ f["status"] != "PASS" for f in fields["fields"]
+ ):
+ raise ValueError("missing HYSTERIA2 field behavior coverage")
+ print(f"HYSTERIA2: PASS ({len(cases)} required cases; {len(FIELDS)} field rows)")
+
+
+def preflight(output):
+ # The normal native gates prove readiness as well as protocol behavior;
+ # this command deliberately never fabricates a protocol PASS.
+ supplied = prepare(output, {"M", "H", "XR"})
+ (output / "peers.json").write_text(
+ json.dumps({k: v[1] for k, v in supplied.items()}, indent=2) + "\n"
+ )
diff --git a/scripts/src/vcore_scripts/protocol_hysteria2_catalog.py b/scripts/src/vcore_scripts/protocol_hysteria2_catalog.py
new file mode 100644
index 0000000..b43a7ee
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_hysteria2_catalog.py
@@ -0,0 +1,329 @@
+"""Frozen HYSTERIA2 requirements and exact structured assertion identities."""
+
+from __future__ import annotations
+
+from collections import Counter
+
+from .protocol_evidence import idle_resources
+
+FIELDS = {
+ *(f"C{i:02}" for i in range(1, 7)),
+ "T01",
+ "T03",
+ "T04",
+ "T05",
+ "T07",
+ "T08",
+ *(f"HY{i:02}" for i in range(1, 9)),
+}
+CFG = [
+ "hysteria2_configuration_follows_its_protocol_feature",
+ "hysteria2_accepts_the_approved_tls_bandwidth_obfs_and_hopping_configuration",
+ "hysteria2_fields_are_strict_normalized_and_credentials_are_not_trimmed",
+]
+UNIT = [
+ "tcp_wire_matches_the_protocol_and_preserves_server_first_bytes",
+ "udp_wire_round_trips_at_budget_and_bounds_malformed_fragments",
+ "udp_reassembly_isolates_sources_duplicates_counts_bytes_and_expiry",
+ "salamander_matches_independent_blake2b256_vector_and_rejects_short_packets",
+ "pacer_limits_actual_bytes_after_one_bounded_burst",
+ "bandwidth_negotiation_obeys_auto_and_the_lower_positive_limit",
+ "application_eof_closes_both_directions_without_consuming_a_tail",
+ "shutdown_wakes_an_already_pending_logical_reader",
+ "a_client_first_write_does_not_steal_a_pending_read_wakeup",
+ "a_new_path_packet_does_not_end_the_old_receive_window",
+ "authenticated_continuation_keeps_group_choice_but_has_a_new_io_deadline",
+ "controlled_path_maps_only_its_authorized_source_and_stops_without_replay",
+]
+SECURITY = (
+ "root-pin",
+ "leaf-pin",
+ "root-pin-wrong-name",
+ "leaf-pin-is-trust",
+ "unknown-ca",
+ "explicit-skip",
+ "wrong-pin",
+ "skip-does-not-override-pin",
+ "wrong-password",
+ "empty-password",
+ "raw-password",
+ "empty-alpn-default",
+ "custom-alpn",
+ "wrong-alpn",
+ "mtls-valid",
+ "mtls-absent",
+ "mtls-expired",
+ "mtls-wrong-ca",
+ "salamander",
+ "salamander-client-only",
+ "salamander-server-only",
+ "salamander-wrong-key",
+ "salamander-wrong-auth",
+)
+M = {
+ "HYSTERIA2-TCP": (
+ "hysteria2_tcp_base",
+ False,
+ ["C01", "C02", "C03", "C04", "T01", "T03", "HY01"],
+ ),
+ "HYSTERIA2-UDP": ("hysteria2_udp_base", False, ["C05", "HY06"]),
+ "HYSTERIA2-TCP-SALAMANDER": ("hysteria2_tcp_base", True, ["HY02", "HY03"]),
+ "HYSTERIA2-UDP-SALAMANDER": ("hysteria2_udp_base", True, ["HY02", "HY03", "HY06"]),
+ "HYSTERIA2-SECURITY": (
+ "native_security_matrix",
+ False,
+ ["T01", "T03", "T04", "T05", "T07", "T08", "HY01", "HY02", "HY03"],
+ ),
+ "HYSTERIA2-BANDWIDTH": ("native_bandwidth_matrix", False, ["HY04", "HY05"]),
+ "HYSTERIA2-CLOSE": ("native_mihomo_close_alignment", False, []),
+ "HYSTERIA2-CLOSE-SALAMANDER": (
+ "native_mihomo_close_alignment",
+ True,
+ ["HY02", "HY03"],
+ ),
+ "HYSTERIA2-OWNED": ("native_owned_lifecycle", False, []),
+ "HYSTERIA2-DEADLINE": ("native_deadline_and_udp_budget", False, ["HY06"]),
+ "HYSTERIA2-LIFE": ("runtime::public_lifecycle", False, []),
+ "HYSTERIA2-ENTRYPOINTS": ("runtime::public_entrypoints", False, ["C05"]),
+ "HYSTERIA2-IPV6-GATES": ("runtime::public_ipv6_and_gates", False, ["C03", "C05"]),
+ "HYSTERIA2-UDP-BOUNDARIES": ("hysteria2::public_udp_boundaries", False, ["HY06"]),
+ "HYSTERIA2-UPSTREAM": ("hysteria2::public_concrete_upstream", False, ["C06"]),
+ "HYSTERIA2-GRAPH": (
+ "hysteria2::public_graph_and_hop_snapshot",
+ False,
+ ["C06", "HY07", "HY08"],
+ ),
+}
+H = {
+ "-".join(
+ (
+ "HYSTERIA2-HOP",
+ "V6" if v6 else "V4",
+ "OBFS" if obfs else "PLAIN",
+ "RANDOM" if random else "FIXED",
+ )
+ ): dict(test="native_hopping", ipv6=v6, obfs=obfs, random_interval=random)
+ for v6 in (False, True)
+ for obfs in (False, True)
+ for random in (False, True)
+}
+H.update(
+ {
+ "HYSTERIA2-UDP-DISABLED": dict(
+ test="native_udp_disabled", ipv6=False, obfs=False, random_interval=False
+ ),
+ "HYSTERIA2-HOP-PROTECT": dict(
+ test="native_hop_protect_rejection",
+ ipv6=False,
+ obfs=False,
+ random_interval=False,
+ ),
+ "HYSTERIA2-HOP-STOP": dict(
+ test="native_stop_during_hop", ipv6=True, obfs=True, random_interval=False
+ ),
+ }
+)
+GATES = {
+ "HYSTERIA2-CFG",
+ "HYSTERIA2-UNIT",
+ "HYSTERIA2-RELEASE",
+ "HYSTERIA2-REGRESSION",
+ "HYSTERIA2-QUALITY",
+ "HYSTERIA2-FEATURES",
+ "HYSTERIA2-SCRIPTS",
+ "HYSTERIA2-PLATFORMS",
+}
+H3 = "HYSTERIA2-H3-REGRESSION"
+
+
+def expected_events(test):
+ public = {
+ "hysteria2_tcp_base": ("HYSTERIA2-BASE", "tcp_ipv4_ipv6_domain_and_measure"),
+ "hysteria2_udp_base": ("HYSTERIA2-BASE", "udp_ipv4_ipv6_domain_fragmentation"),
+ "hysteria2_client_first": ("HYSTERIA2-BASE", "client_first"),
+ }
+ if test in public:
+ expected = {public[test]: 1}
+ if test == "hysteria2_tcp_base":
+ expected["HYSTERIA2-BASE", "tcp_10mib_both_directions"] = 3
+ return expected
+ if test.startswith("runtime::"):
+ result = {("HYSTERIA2-PUBLIC", test): 1}
+ if test == "runtime::public_lifecycle":
+ result["HYSTERIA2-LIFE", "stop_and_remain_quiet"] = 20
+ return result
+ if test.startswith("hysteria2::"):
+ return {("HYSTERIA2-PUBLIC", test.removeprefix("hysteria2::")): 1}
+ if test == "native_security_matrix":
+ return {
+ ("HYSTERIA2-SECURITY", test): 1,
+ **{("HYSTERIA2-SECURITY-CASE", name): 1 for name in SECURITY},
+ }
+ return {
+ (
+ {
+ "native_bandwidth_matrix": "HYSTERIA2-BANDWIDTH",
+ "native_owned_lifecycle": "HYSTERIA2-LIFE",
+ "native_hopping": "HYSTERIA2-HOP",
+ "native_udp_disabled": "HYSTERIA2-UDP-DISABLED",
+ "native_hop_protect_rejection": "HYSTERIA2-HOP",
+ "native_stop_during_hop": "HYSTERIA2-HOP",
+ "native_deadline_and_udp_budget": "HYSTERIA2-NATIVE",
+ "native_mihomo_close_alignment": "HYSTERIA2-NATIVE",
+ }[test],
+ test,
+ ): 20 if test == "native_owned_lifecycle" else 1
+ }
+
+
+def assertions_pass(events, expected):
+ if not events or any(
+ e.get("schema_version") != 1 or e.get("status") not in {"BEGIN", "PASS"}
+ for e in events
+ ):
+ return False
+ actual = Counter((e.get("suite"), e.get("assertion")) for e in events)
+ if actual != Counter({key: count * 2 for key, count in expected.items()}):
+ return False
+ for key, count in expected.items():
+ selected = [e for e in events if (e.get("suite"), e.get("assertion")) == key]
+ if [e["status"] for e in selected] != ["BEGIN", "PASS"] * count:
+ return False
+ for event in selected[1::2]:
+ if event.get("resources") is not None and not idle_resources(
+ event["resources"]
+ ):
+ return False
+ return True
+
+
+def events_pass(events, test):
+ if not assertions_pass(events, expected_events(test)):
+ return False
+ passed = [e for e in events if e["status"] == "PASS"]
+ if test in {
+ "native_hopping",
+ "native_hop_protect_rejection",
+ "native_stop_during_hop",
+ "native_owned_lifecycle",
+ "native_deadline_and_udp_budget",
+ "native_security_matrix",
+ }:
+ owned = [e for e in passed if e["assertion"] == test]
+ if any(not idle_resources(e.get("resources")) for e in owned):
+ return False
+ if test == "native_owned_lifecycle" and any(
+ [p["phase"] for p in e["checkpoints"]]
+ != ["baseline", "after-stop", "quiet"]
+ or any(not idle_resources(p.get("resources")) for p in e["checkpoints"])
+ or e["seconds"] < 5
+ for e in owned
+ ):
+ return False
+ return True
+
+
+def definitions():
+ output = []
+ for identifier in sorted(GATES | set(M) | set(H) | {H3}):
+ kind, test, rows, options = "unit", identifier, [], {}
+ if identifier in M:
+ test, obfs, rows = M[identifier]
+ kind, options = "M", dict(obfs=obfs)
+ elif identifier in H:
+ options = H[identifier]
+ kind, test = "H", options["test"]
+ rows = ["C04", "HY07", "HY08"] if test != "native_udp_disabled" else ["C05"]
+ elif identifier == H3:
+ kind, test = "XR", "shared-quic-h3-native-regression"
+ elif identifier == "HYSTERIA2-CFG":
+ rows = sorted(FIELDS)
+ native = kind != "unit"
+ substage = (
+ "HYSTERIA2.hopping"
+ if kind == "H" and test != "native_udp_disabled"
+ else "HYSTERIA2.bandwidth"
+ if identifier == "HYSTERIA2-BANDWIDTH"
+ else "HYSTERIA2.udp"
+ if "UDP" in identifier
+ else "HYSTERIA2.tcp"
+ if identifier in M
+ else "HYSTERIA2.acceptance"
+ )
+ expected = (
+ CFG
+ if identifier == "HYSTERIA2-CFG"
+ else UNIT
+ if identifier == "HYSTERIA2-UNIT"
+ else CFG + UNIT
+ if identifier == "HYSTERIA2-RELEASE"
+ else [test]
+ )
+ output.append(
+ dict(
+ case_id=identifier,
+ stage="HYSTERIA2",
+ substage=substage,
+ required=True,
+ row_ids=sorted(rows),
+ protocol="hysteria2" if identifier != H3 else "vless",
+ network="quic",
+ security="tls13",
+ udp_codec="hysteria2-datagram" if identifier != H3 else "vless",
+ field_values=options,
+ outer_family="IPv6"
+ if options.get("ipv6")
+ else "IPv4/IPv6"
+ if identifier == "HYSTERIA2-IPV6-GATES"
+ else "IPv4",
+ inner_family="IPv4/IPv6/domain",
+ target_type="isolated synthetic origin"
+ if native
+ else "memory-only/build",
+ upstream_graph="direct/concrete/nested-select"
+ if identifier in {"HYSTERIA2-GRAPH", "HYSTERIA2-UPSTREAM"}
+ else "direct",
+ peer_kind=kind,
+ peer_config=dict(
+ test=test, **{k: v for k, v in options.items() if k != "test"}
+ ),
+ gap_source=dict(
+ reason=(
+ "Mihomo HY2 listener cannot redirect one QUIC state "
+ "across a port set or disable authenticated business "
+ "UDP; official Hysteria provides these gates"
+ ),
+ source="https://github.com/HyNetworks/hysteria/blob/e1366b173ccf5706e1e4630fe8aa654a4b574085/core/server/server.go",
+ )
+ if kind == "H"
+ else dict(
+ reason=(
+ "XHTTP H3 shared-adapter regression uses the XHTTP "
+ "official Xray handler"
+ ),
+ source="https://github.com/XTLS/Xray-core",
+ )
+ if kind == "XR"
+ else None,
+ expected_observation=expected,
+ required_evidence=["structured-assertions", "command", "cleanup"]
+ + (["peer-identity", "isolated-origins"] if native else []),
+ prerequisites=[
+ "owned-host-only-container-network",
+ "official-latest-peer",
+ ]
+ if native
+ else ["rust-toolchain"],
+ runner="native-hysteria2" if kind in {"M", "H"} else "hysteria2-gate",
+ timeout_seconds=3600
+ if identifier == "HYSTERIA2-PLATFORMS"
+ else 900
+ if identifier == H3
+ else 1200
+ if not native
+ else 600
+ if identifier == "HYSTERIA2-BANDWIDTH"
+ else 300,
+ )
+ )
+ return output
diff --git a/scripts/src/vcore_scripts/protocol_hysteria2_hop.py b/scripts/src/vcore_scripts/protocol_hysteria2_hop.py
new file mode 100644
index 0000000..4a5252c
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_hysteria2_hop.py
@@ -0,0 +1,440 @@
+"""Official Hysteria, with redirection confined to an owned Linux container."""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import json
+import os
+import shutil
+import tempfile
+import time
+import urllib.request
+from pathlib import Path
+
+from .builds import CORE_DIR
+from .protocol_containers import NETWORK, ContainerLab, ContainerPeer, command
+from .protocol_evidence import read_events
+from .protocol_fixtures import certificates
+from .protocol_hysteria2_catalog import events_pass
+from .protocol_inputs import redact, source_identity
+from .protocol_peers import run_command
+
+
+def guest(peer, *argv, timeout=30):
+ # Container CLI can exit zero even when its guest command fails.
+ result = run_command(
+ [
+ "container",
+ "exec",
+ peer.name,
+ "/bin/sh",
+ "-c",
+ '"$@" 2>&1\ncode=$?\nprintf "\\nVCORE_STATUS=%s\\n" "$code"',
+ "fixture",
+ *argv,
+ ],
+ timeout=timeout,
+ )
+ output = result.stdout.decode(errors="replace")
+ if result.returncode != 0 or not result.cleanup:
+ raise RuntimeError(
+ f"isolated guest {argv[0]} failed after {result.seconds:.1f}s "
+ f"(exit={result.returncode}, cleanup={result.cleanup}): "
+ f"{redact(output[-2048:])}"
+ )
+ body, marker, code = output.rpartition("\nVCORE_STATUS=")
+ if not marker or code.strip() != "0":
+ raise RuntimeError(
+ f"isolated guest operation failed: {argv[0]}: {redact(body[-2048:])}"
+ )
+ return body
+
+
+def native_binary(output):
+ url = "https://github.com/HyNetworks/hysteria/releases/latest/download/hysteria-linux-arm64"
+ path = output / "hysteria"
+ digest, total, deadline = hashlib.sha256(), 0, time.monotonic() + 90
+ request = urllib.request.Request(url, headers={"User-Agent": "VCore-interop"})
+ with (
+ urllib.request.urlopen(request, timeout=30) as response,
+ path.open("xb") as target,
+ ):
+ if not response.geturl().startswith("https://"):
+ raise RuntimeError("native download redirected outside HTTPS")
+ while chunk := response.read(1024 * 1024):
+ total += len(chunk)
+ if total > 128 * 1024 * 1024 or time.monotonic() > deadline:
+ raise RuntimeError("native binary download budget exceeded")
+ target.write(chunk)
+ digest.update(chunk)
+ path.chmod(0o755)
+ return path, {"source_url": url, "binary_sha256": digest.hexdigest()}
+
+
+def packages(lab, stack, root):
+ """Only package preparation has external egress; no server runs there."""
+ root.mkdir()
+ peer = ContainerPeer(lab, root, "hysteria2-packages")
+ lab.record["peers"].append(peer.record)
+ stack.callback(peer.stop)
+ command(
+ "run",
+ "--detach",
+ "--name",
+ peer.name,
+ "--label",
+ f"purpose={NETWORK}",
+ "--label",
+ f"vcore-run={lab.run_id}",
+ "--network",
+ "default",
+ "--arch",
+ "arm64",
+ "--cpus",
+ "1",
+ "--memory",
+ "256M",
+ "--mount",
+ f"type=bind,source={root},target=/packages",
+ "--entrypoint",
+ "/bin/sleep",
+ lab.image,
+ "360",
+ timeout=45,
+ )
+ peer.record.update(
+ started=True, role="package-preparation-only", network_mode="default"
+ )
+ guest(peer, "apk", "update", timeout=60)
+ guest(
+ peer,
+ "apk",
+ "fetch",
+ "--recursive",
+ "--output",
+ "/packages",
+ "nftables",
+ timeout=240,
+ )
+ found = sorted(root.glob("*.apk"))
+ if not found:
+ raise RuntimeError("missing native firewall packages")
+ lab.record["firewall_packages"] = {
+ path.name: hashlib.sha256(path.read_bytes()).hexdigest() for path in found
+ }
+ peer.stop()
+ return found
+
+
+def run(
+ output: Path,
+ *,
+ ipv6=False,
+ obfs=False,
+ random_interval=False,
+ test="native_hopping",
+ supplied=None,
+):
+ if test not in {
+ "native_hopping",
+ "native_udp_disabled",
+ "native_hop_protect_rejection",
+ "native_stop_during_hop",
+ }:
+ raise ValueError("unknown native H gate")
+ output = output.resolve()
+ output.mkdir(parents=True, exist_ok=False)
+ report = dict(
+ stage="HYSTERIA2",
+ scope="incremental-native-H",
+ source=source_identity(),
+ status="NOT RUN",
+ isolation={},
+ cases=[],
+ ipv6=ipv6,
+ obfs=obfs,
+ random_interval=random_interval,
+ )
+ try:
+ if supplied is None:
+ binary, report["peer"] = native_binary(output)
+ else:
+ binary, report["peer"], _, _ = supplied
+ if (
+ hashlib.sha256(binary.read_bytes()).hexdigest()
+ != report["peer"]["binary_sha256"]
+ ):
+ raise RuntimeError("supplied H artifact identity mismatch")
+ lab = ContainerLab(report["isolation"], mtu=1500)
+ with (
+ tempfile.TemporaryDirectory(prefix="private-", dir=output) as temporary,
+ contextlib.ExitStack() as stack,
+ ):
+ root = Path(temporary)
+ root.chmod(0o700)
+ if supplied is None:
+ apks = packages(lab, stack, root / "apks")
+ else:
+ _, _, apks, digests = supplied
+ if {
+ p.name: hashlib.sha256(p.read_bytes()).hexdigest() for p in apks
+ } != digests:
+ raise RuntimeError("supplied firewall package identity mismatch")
+ report["isolation"]["firewall_packages"] = digests
+ origin_dir, server_dir = root / "origin", root / "server"
+ origin_dir.mkdir()
+ server_dir.mkdir()
+ shutil.copyfile(
+ Path(__file__).with_name("container_udp_origin.py"),
+ origin_dir / "origin.py",
+ )
+ shutil.copy2(binary, server_dir / "hysteria")
+ (server_dir / "apks").mkdir()
+ for path in apks:
+ shutil.copy2(path, server_dir / "apks" / path.name)
+ cert, key, pin = certificates(server_dir)
+ origin = lab.start(
+ stack,
+ origin_dir,
+ "hysteria2-h-origin",
+ [
+ "env",
+ "VCORE_ISOLATED_ORIGIN=1",
+ "python",
+ "-B",
+ "/data/fixture/origin.py",
+ ],
+ )
+ server = lab.start(
+ stack,
+ server_dir,
+ "hysteria2-h-peer",
+ [
+ "env",
+ "HYSTERIA_FIREWALL_BACKEND=nftables",
+ "/data/fixture/hysteria",
+ "server",
+ "--disable-update-check",
+ "--log-format",
+ "json",
+ "-c",
+ "/data/fixture/config.json",
+ ],
+ net_admin=True,
+ )
+ guest(
+ server,
+ "apk",
+ "add",
+ "--no-network",
+ *[f"/data/fixture/apks/{path.name}" for path in apks],
+ timeout=45,
+ )
+ report["peer"]["version"] = guest(
+ server, "/data/fixture/hysteria", "version"
+ ).strip()
+ if (
+ guest(server, "sha256sum", "/data/fixture/hysteria").split()[0]
+ != report["peer"]["binary_sha256"]
+ ):
+ raise RuntimeError("native binary identity mismatch")
+ report["isolation"]["nftables"] = guest(server, "nft", "--version").strip()
+ (server_dir / "hosts").write_text(
+ "127.0.0.1 localhost\n::1 localhost\n"
+ f"{origin.ipv4} vcore-fixture.test\n"
+ )
+ guest(server, "cp", "/data/fixture/hosts", "/etc/hosts")
+ # Pre-DNAT observations: native Hysteria owns its separate redirect table.
+ rules = (
+ "table inet vcore_hysteria2 { chain observe { "
+ "type filter hook prerouting priority -150; policy accept; "
+ )
+ for port in range(23010, 23013):
+ rules += f'udp dport {port} counter comment "p{port}"; '
+ rules += "}\n}\n"
+ (server_dir / "observe.nft").write_text(rules)
+ guest(server, "nft", "-f", "/data/fixture/observe.nft")
+ password = "synthetic-hysteria2-fixture"
+ config = dict(
+ # Native Hysteria deliberately treats [::] as IPv6-only.
+ listen=f"[{server.ipv6}]:23010-23012"
+ if ipv6
+ else f"{server.ipv4}:23010-23012",
+ tls=dict(
+ cert=f"/data/fixture/{cert.name}", key=f"/data/fixture/{key.name}"
+ ),
+ auth=dict(type="password", password=password),
+ trafficStats=dict(listen="0.0.0.0:24003"),
+ )
+ node = dict(
+ name="peer",
+ type="hysteria2",
+ server=server.ipv6 if ipv6 else server.ipv4,
+ ports="23010-23012",
+ **{"hop-interval": "5-7" if random_interval else 5},
+ password=password,
+ udp=True,
+ sni="localhost",
+ fingerprint=pin,
+ )
+ if obfs:
+ config["obfs"] = dict(
+ type="salamander",
+ salamander=dict(password="independent-obfs-fixture"),
+ )
+ node.update(
+ obfs="salamander", **{"obfs-password": "independent-obfs-fixture"}
+ )
+ if test == "native_udp_disabled":
+ config["disableUDP"] = True
+ (server_dir / "config.json").write_text(json.dumps(config))
+ fixture = root / "input.json"
+ fixture.write_text(
+ json.dumps(
+ dict(
+ isolation="containers",
+ origin_control=f"{origin.ipv4}:24000",
+ origin_ipv4=origin.ipv4,
+ origin_ipv6=origin.ipv6,
+ node=node,
+ )
+ )
+ )
+ origin.release()
+ server.release()
+ origin.wait_tcp(24000)
+ server.wait_tcp(24003)
+ result = run_command(
+ [
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ "hysteria2_native",
+ test,
+ "--",
+ "--ignored",
+ "--exact",
+ "--nocapture",
+ ],
+ cwd=CORE_DIR,
+ timeout=180,
+ limit=4 * 1024 * 1024,
+ env=dict(
+ os.environ,
+ VCORE_VLESS_INPUT=str(fixture),
+ VCORE_CASE_EVENTS=str(output / "hysteria2-events.jsonl"),
+ VCORE_HOP_OBSERVATIONS=str(output / "hopping.json"),
+ ),
+ )
+ (output / "test.log").write_text(
+ redact(result.stdout.decode(errors="replace"))
+ )
+ raw_log = command("logs", server.name)
+ connected = sum(
+ '"msg":"client connected"' in line for line in raw_log.splitlines()
+ )
+ report["auth_connections"] = connected
+ (output / "server.log").write_text(
+ redact(raw_log.replace(password, ""))
+ )
+ rules = json.loads(
+ guest(server, "nft", "-j", "list", "table", "inet", "vcore_hysteria2")
+ )
+ counts = {}
+ for entry in rules["nftables"]:
+ if "rule" in entry:
+ rule = entry["rule"]
+ counts[rule["comment"]] = next(
+ item["counter"]["packets"]
+ for item in rule["expr"]
+ if "counter" in item
+ )
+ report["entry_port_packets"] = counts
+ passed = (
+ result.returncode == 0
+ and result.cleanup
+ and (output / "hysteria2-events.jsonl").exists()
+ and events_pass(read_events(output / "hysteria2-events.jsonl"), test)
+ and connected == 1
+ and sum(value > 0 for value in counts.values())
+ >= (2 if test == "native_hopping" else 1)
+ )
+ report["cases"].append(
+ dict(
+ case_id=test,
+ exit_code=result.returncode,
+ seconds=result.seconds,
+ command_cleanup=result.cleanup,
+ command=[
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ "hysteria2_native",
+ test,
+ "--",
+ "--ignored",
+ "--exact",
+ "--nocapture",
+ ],
+ status="PASS" if passed else "FAIL",
+ )
+ )
+ report["status"] = "PASS" if passed else "FAIL"
+ except (OSError, RuntimeError, ValueError) as error:
+ report.update(
+ status="FAIL",
+ reason=str(error)
+ if isinstance(error, RuntimeError)
+ else type(error).__name__,
+ )
+ finally:
+ report["cleanup"] = all(
+ peer["joined"] for peer in report["isolation"].get("peers", [])
+ )
+ report["source_unchanged"] = (
+ source_identity()["source_tree_sha256"]
+ == report["source"]["source_tree_sha256"]
+ )
+ if not report["source_unchanged"] or not report["cleanup"]:
+ report["status"] = "FAIL"
+ (output / "report.json").write_text(json.dumps(report, indent=2) + "\n")
+ return report
+
+
+if __name__ == "__main__":
+ import sys
+
+ result = run(
+ Path(sys.argv[1]),
+ ipv6="--ipv6" in sys.argv,
+ obfs="--salamander" in sys.argv,
+ random_interval="--random" in sys.argv,
+ test=(
+ sys.argv[sys.argv.index("--test") + 1]
+ if "--test" in sys.argv
+ else "native_udp_disabled"
+ if "--udp-disabled" in sys.argv
+ else "native_hopping"
+ ),
+ )
+ print(
+ json.dumps(
+ {
+ key: result.get(key)
+ for key in (
+ "status",
+ "reason",
+ "cleanup",
+ "cases",
+ "auth_connections",
+ "entry_port_packets",
+ )
+ }
+ )
+ )
+ raise SystemExit(0 if result["status"] == "PASS" and result["cleanup"] else 1)
diff --git a/scripts/src/vcore_scripts/protocol_inputs.py b/scripts/src/vcore_scripts/protocol_inputs.py
new file mode 100644
index 0000000..a313f05
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_inputs.py
@@ -0,0 +1,133 @@
+"""Reproducible, nonsensitive input identity for one local protocol run."""
+
+from __future__ import annotations
+
+import hashlib
+import platform
+import re
+import sys
+import tomllib
+from datetime import UTC, datetime
+from pathlib import Path
+
+from .builds import CORE_DIR
+from .protocol_peers import run_command
+
+CODE_PATHS = [
+ "Cargo.toml",
+ "Cargo.lock",
+ "src",
+ "crates",
+ "tests",
+ "scripts",
+ "include",
+]
+
+
+def sha256(path: Path) -> str:
+ with path.open("rb") as stream:
+ return hashlib.file_digest(stream, "sha256").hexdigest()
+
+
+def command_output(command: list[str]) -> bytes:
+ result = run_command(command, cwd=CORE_DIR, timeout=20, limit=8 * 1024 * 1024)
+ if result.returncode != 0:
+ raise RuntimeError("cannot record protocol input identity")
+ return result.stdout
+
+
+def source_identity() -> dict:
+ paths = (
+ command_output(
+ ["git", "ls-files", "-co", "--exclude-standard", "-z", "--", *CODE_PATHS]
+ )
+ .decode()
+ .split("\0")
+ )
+ digest = hashlib.sha256()
+ for name in sorted(set(paths) - {""}):
+ path = CORE_DIR / name
+ if not path.exists():
+ continue
+ if path.is_symlink() or not path.is_file():
+ raise ValueError("non-file source input")
+ digest.update(name.encode() + b"\0" + bytes.fromhex(sha256(path)))
+ patch = command_output(["git", "diff", "--binary", "HEAD", "--", *CODE_PATHS])
+ return {
+ "parent_commit": command_output(["git", "rev-parse", "HEAD"]).decode().strip(),
+ "source_tree_sha256": digest.hexdigest(),
+ "dirty_patch_sha256": hashlib.sha256(patch).hexdigest(),
+ "lock_sha256": sha256(CORE_DIR / "Cargo.lock"),
+ }
+
+
+def same_source(before: dict, after: dict) -> bool:
+ """Compare actual inputs, not a patch changed merely by staging new files."""
+ return all(
+ before[key] == after[key]
+ for key in ("parent_commit", "source_tree_sha256", "lock_sha256")
+ )
+
+
+def run_identity(stage: str, selected: list[dict], preflight: bool) -> dict:
+ record = source_identity()
+ lock = tomllib.loads((CORE_DIR / "Cargo.lock").read_text())
+ tls = [
+ {key: package[key] for key in ["name", "version", "source"]}
+ for package in lock["package"]
+ if package["name"] in {"rustls", "tokio-rustls", "ring"}
+ ]
+ text = (CORE_DIR / "src/lib.rs").read_text()
+ record.update(
+ schema_version=1,
+ stage=stage,
+ mode="preflight" if preflight else "execute",
+ started_utc=datetime.now(UTC).isoformat(),
+ os=platform.system(),
+ os_version=platform.release(),
+ architecture=platform.machine(),
+ python=platform.python_version(),
+ rustls=tls,
+ invoke_api_version=int(re.search(r"INVOKE_API_VERSION: u32 = (\d+)", text)[1]),
+ config_version=int(re.search(r"CONFIG_VERSION: u8 = (\d+)", text)[1]),
+ features=["all-features", "independent-feature-smokes"],
+ selected_cases=[case["case_id"] for case in selected],
+ commands=[],
+ cleanup=False,
+ source_unchanged=False,
+ artifacts=[],
+ suite_timeout_seconds=sum(case["timeout_seconds"] for case in selected) + 1800,
+ )
+ record["rustc"] = command_output(["rustc", "-Vv"]).decode().strip()
+ record["cargo"] = command_output(["cargo", "--version"]).decode().strip()
+ if sys.platform == "darwin":
+ record["xcode"] = command_output(["xcodebuild", "-version"]).decode().strip()
+ record["sdk"] = command_output(["xcrun", "--show-sdk-version"]).decode().strip()
+ return record
+
+
+def redact(text: str) -> str:
+ text = text.replace(str(CORE_DIR), "")
+ text = re.sub(
+ r"(?i)(authorization\s*[:=]\s*)(?:Bearer|Basic)\s+[^\s,}]+",
+ r"\1",
+ text,
+ )
+ text = re.sub(
+ r"(?i)-----BEGIN .*?PRIVATE KEY-----.*?-----END .*?PRIVATE KEY-----",
+ "",
+ text,
+ flags=re.S,
+ )
+ text = re.sub(
+ r"[0-9a-fA-F]{8}(?:-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}", "", text
+ )
+ text = re.sub(
+ r"(?i)((?:password|authorization|private[-_]key|token)\s*[:=]\s*)([^\s,}]+)",
+ r"\1",
+ text,
+ )
+ text = re.sub(
+ r"/(?:Users|home|private/var|var/folders)/[^\s\"']+", "", text
+ )
+ return text
diff --git a/scripts/src/vcore_scripts/protocol_integration_acceptance.py b/scripts/src/vcore_scripts/protocol_integration_acceptance.py
new file mode 100644
index 0000000..7f48640
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_integration_acceptance.py
@@ -0,0 +1,357 @@
+"""INTEGRATION execution and independent reconstruction of raw integration evidence."""
+
+from __future__ import annotations
+
+import json
+
+from .protocol_evidence import read_events, read_json
+from .protocol_hysteria2_catalog import assertions_pass
+from .protocol_integration_catalog import LOCAL, PAIRS, definitions
+from .protocol_integration_checks import envelope, runtime_pass
+from .protocol_integration_local import commands, passed
+from .protocol_integration_shared import hops_pass, shared_pass
+from .protocol_security_acceptance import result
+
+
+def pair_pass(identifier, record, directory):
+ from .protocol_integration_native import rust_command
+
+ first, last = PAIRS[identifier]
+ targets = 2 if last == "trojan" else 3
+ events = read_events(directory / (identifier + "-events.jsonl"))
+ observation = read_json(directory / (identifier + "-observations.json"))
+ expected = [
+ dict(
+ outer_ipv6=v6,
+ nested_select=group,
+ tcp_target_kinds=3,
+ tcp_bytes_each_direction=31457280,
+ udp_target_kinds=targets,
+ udp_packets=targets * 400,
+ udp_sizes=[1, 64, 512, 1200],
+ server_first=True,
+ client_first=True,
+ ports_rebound=True,
+ )
+ for v6 in (False, True)
+ for group in (False, True)
+ ]
+ return (
+ record.get("case_id") == identifier
+ and record.get("command") == rust_command()
+ and type(record.get("exit_code")) is int
+ and record["exit_code"] == 0
+ and record.get("command_cleanup") is True
+ and observation
+ == dict(
+ first=first,
+ last=last,
+ paths=expected,
+ domain_native=[
+ dict(
+ outer_ipv6=v6,
+ nested_select=group,
+ peer="XR",
+ udp_packets=400,
+ target="domain",
+ )
+ for v6 in (False, True)
+ for group in (False, True)
+ ]
+ if last == "trojan"
+ else [],
+ budgets=[
+ dict(
+ transmit=tx,
+ receive=rx,
+ roundtrip_size=min(tx, rx),
+ packets=100,
+ oversize_rejected_before_origin=True,
+ )
+ for tx, rx in ((128, 128), (512, 256))
+ ],
+ routed_udp=dict(
+ upstream_business_udp_disabled=True,
+ carrier_tcp=True,
+ carrier_udp=True,
+ leaf_business_udp_rejected=True,
+ ),
+ carrier_capability=dict(
+ upstream_datagrams="rejected",
+ tcp_allowed=last != "hysteria2",
+ udp_allowed=last not in {"ss", "socks5", "hysteria2"},
+ no_bypass=True,
+ ),
+ )
+ and assertions_pass(
+ events,
+ {
+ ("INTEGRATION-PAIR", "ordered_pair"): 1,
+ ("INTEGRATION-BASE", "tcp_10mib_both_directions"): 12,
+ ("INTEGRATION-PAIR", "directional_budget"): 1,
+ ("INTEGRATION-PAIR", "routed_udp_permission"): 1,
+ ("INTEGRATION-PAIR", "carrier_capability"): 1,
+ **(
+ {("INTEGRATION-PAIR", "native_domain_terminal"): 1}
+ if last == "trojan"
+ else {}
+ ),
+ },
+ )
+ )
+
+
+def execute(cases, run, output, results):
+ from .protocol_containers import frozen_image
+ from .protocol_harness import _command
+ from .protocol_hysteria2_acceptance import prepare
+ from .protocol_integration_native import run as run_pairs
+ from .protocol_integration_shared import hops_run, shared_run
+ from .protocol_integration_suite import CONSUMERS
+ from .protocol_integration_suite import run as run_suite
+
+ by_id = {c["case_id"]: c for c in cases}
+ supplied, peers = {}, {}
+ source = {
+ k: run[k]
+ for k in (
+ "parent_commit",
+ "source_tree_sha256",
+ "dirty_patch_sha256",
+ "lock_sha256",
+ )
+ }
+
+ def save(identifier, good, cleanup=True):
+ results[identifier] = result(by_id[identifier], good, cleanup)
+ print(identifier + ": " + results[identifier]["status"], flush=True)
+ if not good:
+ raise RuntimeError("INTEGRATION gate failed: " + identifier)
+
+ try:
+ for identifier in sorted(by_id.keys() & LOCAL):
+ records, events = [], []
+ for i, argv in enumerate(commands(identifier)):
+ name = f"{identifier}-{i}"
+ path = output / (name + "-events.jsonl")
+ _command(
+ run,
+ output,
+ name,
+ [v.replace("{output}", str(output)) for v in argv],
+ 3600,
+ events=path,
+ )
+ records.append(run["commands"][-1])
+ if path.exists():
+ events += read_events(path)
+ if records[-1]["exit_code"] != 0 or not records[-1]["cleanup"]:
+ save(identifier, False, records[-1]["cleanup"])
+ script = (
+ read_json(output / "script-tests.json")
+ if identifier == "INTEGRATION-SCRIPTS"
+ else None
+ )
+ save(identifier, passed(identifier, records, events, script))
+ if set(by_id) <= LOCAL:
+ return
+ with frozen_image(output / "container-image-pull.log") as snapshot:
+ run["container_image"] = snapshot
+ kinds = {"M"}
+ if "INTEGRATION-SHARED" in by_id:
+ kinds |= {"XR", "V2"}
+ if any(PAIRS[i][1] == "trojan" for i in by_id.keys() & PAIRS.keys()):
+ kinds.add("XR")
+ if "INTEGRATION-HY2-HOP" in by_id:
+ kinds.add("H")
+ supplied = prepare(output, kinds)
+ peers = {k: v[1] for k, v in supplied.items()}
+ digest = snapshot["digest"]
+ # Each group is rerun from this source/image/peer scope. Historical
+ # reports are never imported into results.
+ selected = sorted(by_id.keys() & PAIRS.keys())
+ if selected:
+ directory = output / "pairs"
+ report = run_pairs(
+ directory,
+ selected,
+ supplied=supplied["M"],
+ domain_peer=supplied.get("XR"),
+ )
+ if [r["case_id"] for r in report["cases"]] != selected:
+ raise RuntimeError("INTEGRATION ordered-pair selection differs")
+ for record in report["cases"]:
+ identifier = record["case_id"]
+ save(
+ identifier,
+ envelope(report, peers, source, digest)
+ and pair_pass(identifier, record, directory),
+ report["cleanup"],
+ )
+ selected = sorted(
+ by_id.keys() & CONSUMERS.keys(),
+ key=lambda k: (k == "INTEGRATION-SOAK", k),
+ )
+ if selected:
+ directory = output / "runtime"
+ report = run_suite(directory, selected, supplied=supplied["M"])
+ peers.update(report["peers"])
+ if [r["case_id"] for r in report["cases"]] != selected:
+ raise RuntimeError("INTEGRATION runtime selection differs")
+ for record in report["cases"]:
+ identifier = record["case_id"]
+ save(
+ identifier,
+ envelope(report, peers, source, digest)
+ and runtime_pass(identifier, record, directory),
+ report["cleanup"],
+ )
+ if "INTEGRATION-HY2-HOP" in by_id:
+ hops_run(output / "hop", supplied["H"])
+ save(
+ "INTEGRATION-HY2-HOP",
+ hops_pass(output / "hop", peers, source, digest),
+ )
+ if "INTEGRATION-SHARED" in by_id:
+ shared_run(
+ output / "shared",
+ {k: v for k, v in supplied.items() if k in {"M", "XR", "V2"}},
+ )
+ save(
+ "INTEGRATION-SHARED",
+ shared_pass(output / "shared", peers, source, digest),
+ )
+ finally:
+ (output / "peers.json").write_text(json.dumps(peers, indent=2) + "\n")
+
+
+def check(run_dir, cases, run, results, peers, paths):
+ from .protocol_containers import IMAGE
+ from .protocol_evidence import HEX
+ from .protocol_inputs import redact
+ from .protocol_integration_suite import CONSUMERS
+
+ observed_paths = {
+ str(p.relative_to(run_dir))
+ for p in run_dir.rglob("*")
+ if p.is_file()
+ and p.suffix in {".json", ".jsonl", ".log", ".md"}
+ and "binaries" not in p.parts
+ and p.name != "run.json"
+ }
+ if set(paths) != observed_paths:
+ raise ValueError("unhashed or missing INTEGRATION evidence artifact")
+ snapshot = run.get("container_image", {})
+ digest = snapshot.get("digest", "")
+ if not (
+ digest.startswith("sha256:")
+ and HEX.fullmatch(digest[7:])
+ and snapshot
+ == dict(
+ tag=IMAGE,
+ digest=digest,
+ command=["container", "image", "pull", IMAGE],
+ exit_code=0,
+ cleanup=True,
+ log="container-image-pull.log",
+ )
+ and snapshot["log"] in paths
+ and cases == definitions()
+ and set(peers) == {"M", "XR", "V2", "H", "SS"}
+ and {"script-tests.json", "package-preparation.json"} <= set(paths)
+ ):
+ raise ValueError("incomplete INTEGRATION scope, image or peer identities")
+ source = {
+ k: run[k]
+ for k in (
+ "parent_commit",
+ "source_tree_sha256",
+ "dirty_patch_sha256",
+ "lock_sha256",
+ )
+ }
+ records = run.get("commands", [])
+ names = {
+ f"{identifier}-{i}"
+ for identifier in LOCAL
+ for i, _ in enumerate(commands(identifier))
+ }
+ if len(records) != len(names) or {r.get("name") for r in records} != names:
+ raise ValueError("missing, duplicate or extra INTEGRATION local command")
+ pair_report = read_json(run_dir / "pairs/integration-native.json")
+ runtime_report = read_json(run_dir / "runtime/integration-suite.json")
+ expected_runtime = sorted(
+ {c["case_id"] for c in cases} & CONSUMERS.keys(),
+ key=lambda k: (k == "INTEGRATION-SOAK", k),
+ )
+ if (
+ [r.get("case_id") for r in pair_report.get("cases", [])] != sorted(PAIRS)
+ or [r.get("case_id") for r in runtime_report.get("cases", [])]
+ != expected_runtime
+ or set(pair_report.get("peers", {})) != {"M", "XR"}
+ or set(runtime_report.get("peers", {})) != {"M", "SS"}
+ or runtime_report.get("ssserver_policy")
+ != dict(
+ outbound_udp_allow_fragmentation=True,
+ inbound_udp_allow_fragmentation=True,
+ guest_mtu=1500,
+ )
+ ):
+ raise ValueError(
+ "missing INTEGRATION ordered pairs, runtime gates or native SS policy"
+ )
+ actual = {r["case_id"]: r for r in results}
+ for case in cases:
+ identifier = case["case_id"]
+ if identifier in LOCAL:
+ selected, events = [], []
+ for i, argv in enumerate(commands(identifier)):
+ record = next(r for r in records if r["name"] == f"{identifier}-{i}")
+ if (
+ record.get("command")
+ != [redact(v.replace("{output}", str(run_dir))) for v in argv]
+ or record.get("log") not in paths
+ ):
+ raise ValueError("INTEGRATION command or log changed")
+ selected.append(record)
+ path = run_dir / f"{identifier}-{i}-events.jsonl"
+ if path.exists():
+ events += read_events(path)
+ good = passed(
+ identifier,
+ selected,
+ events,
+ read_json(run_dir / "script-tests.json")
+ if identifier == "INTEGRATION-SCRIPTS"
+ else None,
+ )
+ elif identifier in PAIRS or identifier in CONSUMERS:
+ pair = identifier in PAIRS
+ report = pair_report if pair else runtime_report
+ record = next(r for r in report["cases"] if r["case_id"] == identifier)
+ directory = run_dir / ("pairs" if pair else "runtime")
+ good = envelope(report, peers, source, digest) and (
+ pair_pass if pair else runtime_pass
+ )(identifier, record, directory)
+ elif identifier == "INTEGRATION-HY2-HOP":
+ good = hops_pass(run_dir / "hop", peers, source, digest)
+ else:
+ good = shared_pass(run_dir / "shared", peers, source, digest)
+ if not good or result(case, good, True) != actual[identifier]:
+ raise ValueError("INTEGRATION raw evidence does not pass: " + identifier)
+ print(
+ f"INTEGRATION: PASS ({len(cases)} required gates; 49 pairs, "
+ "100 lifetimes, 100 rebuilds, 1800-second soak)"
+ )
+
+
+def preflight(output):
+ from .protocol_containers import frozen_image
+ from .protocol_hysteria2_acceptance import prepare
+
+ # Downloads and container package setup only; never reports behavior PASS.
+ with frozen_image(output / "container-image-pull.log"):
+ supplied = prepare(output, {"M", "XR", "V2", "H"})
+ (output / "peers.json").write_text(
+ json.dumps({k: v[1] for k, v in supplied.items()}, indent=2) + "\n"
+ )
diff --git a/scripts/src/vcore_scripts/protocol_integration_catalog.py b/scripts/src/vcore_scripts/protocol_integration_catalog.py
new file mode 100644
index 0000000..e62b336
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_integration_catalog.py
@@ -0,0 +1,78 @@
+"""Cross-protocol integration requirements and descriptive coverage categories."""
+
+from __future__ import annotations
+
+PROTOCOLS = ("socks5", "anytls", "ss", "trojan", "vmess", "vless", "hysteria2")
+PAIRS = {
+ f"INTEGRATION-PAIR-{first.upper()}-{last.upper()}": (first, last)
+ for first in PROTOCOLS
+ for last in PROTOCOLS
+}
+GATES = {
+ "INTEGRATION-ENTRYPOINTS": "routing",
+ "INTEGRATION-GRAPH": "routing",
+ "INTEGRATION-DNS-MEASURE": "routing",
+ "INTEGRATION-SS-ALGORITHMS": "routing",
+ "INTEGRATION-SS-EIH": "routing",
+ "INTEGRATION-LIFECYCLE": "lifecycle",
+ "INTEGRATION-REBUILD": "lifecycle",
+ "INTEGRATION-FAILURES": "lifecycle",
+ "INTEGRATION-SOAK": "pressure",
+ "INTEGRATION-HY2-HOP": "pressure",
+ "INTEGRATION-DEBUG": "regression",
+ "INTEGRATION-RELEASE": "regression",
+ "INTEGRATION-QUALITY": "regression",
+ "INTEGRATION-FEATURES": "regression",
+ "INTEGRATION-SCRIPTS": "regression",
+ "INTEGRATION-SHARED": "regression",
+}
+LOCAL = {
+ "INTEGRATION-DEBUG",
+ "INTEGRATION-RELEASE",
+ "INTEGRATION-QUALITY",
+ "INTEGRATION-FEATURES",
+ "INTEGRATION-SCRIPTS",
+}
+
+
+def definitions():
+ result = []
+ for identifier in sorted(PAIRS.keys() | GATES.keys()):
+ pair = PAIRS.get(identifier)
+ local = identifier in LOCAL
+ result.append(
+ dict(
+ case_id=identifier,
+ stage="INTEGRATION",
+ substage=f"INTEGRATION.{GATES.get(identifier, 'routing')}",
+ required=True,
+ row_ids=["C06"] if pair else [],
+ protocol="integration",
+ network="seven-protocol-graph",
+ security="per-frozen-consumer",
+ udp_codec="per-protocol",
+ field_values={"first": pair[0], "last": pair[1]} if pair else {},
+ outer_family="IPv4/IPv6",
+ inner_family="IPv4/IPv6/domain",
+ target_type="memory-only/build" if local else "isolated origin",
+ upstream_graph="concrete/nested-select" if pair else "per-gate",
+ peer_kind="unit"
+ if local
+ else "H"
+ if identifier == "INTEGRATION-HY2-HOP"
+ else "SS"
+ if identifier == "INTEGRATION-SS-EIH"
+ else "M",
+ peer_config={"group": identifier},
+ gap_source=None,
+ expected_observation=[identifier],
+ required_evidence=["command", "structured-assertions", "cleanup"]
+ + ([] if local else ["peer-identity", "isolated-origins"]),
+ prerequisites=["rust-toolchain"]
+ if local
+ else ["owned-host-only-container-network", "official-latest-peer"],
+ runner="integration-pair" if pair else "integration-gate",
+ timeout_seconds=3600 if not pair else 300,
+ )
+ )
+ return result
diff --git a/scripts/src/vcore_scripts/protocol_integration_checks.py b/scripts/src/vcore_scripts/protocol_integration_checks.py
new file mode 100644
index 0000000..f53e801
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_integration_checks.py
@@ -0,0 +1,189 @@
+"""Raw runtime observations and native isolation, independent of run status."""
+
+from __future__ import annotations
+
+from .protocol_evidence import HEX, idle_resources, read_events, read_json
+from .protocol_hysteria2_catalog import assertions_pass
+from .protocol_integration_catalog import PROTOCOLS
+from .protocol_integration_metrics import lifetimes, rebuild, soak
+from .protocol_integration_native import rust_command
+from .protocol_integration_suite import CONSUMERS
+
+
+def envelope(report, peers, source, digest, *, single=None):
+ isolation = report.get("isolation", {})
+ identities = {single: report.get("peer", {})} if single else report.get("peers", {})
+ owned = isolation.get("peers", [])
+ urls = {
+ "M": "MetaCubeX/mihomo",
+ "XR": "XTLS/Xray-core",
+ "V2": "v2fly/v2ray-core",
+ "SS": "shadowsocks/shadowsocks-rust",
+ "H": "HyNetworks/hysteria",
+ }
+ return bool(
+ report.get("status") == "PASS"
+ and report.get("cleanup") is True
+ and report.get("source_unchanged") is True
+ and report.get("source") == source
+ and isolation.get("network_mode") == "hostOnly"
+ and isolation.get("host_servers") is False
+ and isolation.get("guest_mtu") == 1500
+ and isolation.get("image_digest") == digest
+ and digest.startswith("sha256:")
+ and HEX.fullmatch(digest[7:])
+ and owned
+ and all(p.get("started") is True and p.get("joined") is True for p in owned)
+ and identities
+ and all(
+ kind in urls
+ and identity == peers.get(kind)
+ and identity.get("version")
+ and HEX.fullmatch(identity.get("binary_sha256", ""))
+ and (kind == "H" or HEX.fullmatch(identity.get("archive_sha256", "")))
+ and identity.get("source_url", "").startswith(
+ f"https://github.com/{urls[kind]}/releases/"
+ )
+ for kind, identity in identities.items()
+ )
+ )
+
+
+def runtime_pass(identifier, record, directory):
+ if not (
+ record.get("case_id") == identifier
+ and record.get("command") == rust_command(CONSUMERS[identifier])
+ and type(record.get("exit_code")) is int
+ and record["exit_code"] == 0
+ and record.get("command_cleanup") is True
+ ):
+ return False
+ value = read_json(directory / (identifier + "-observations.json"))
+ events = read_events(directory / (identifier + "-events.jsonl"))
+ protocols = list(PROTOCOLS)
+ expected = {(identifier, p): 1 for p in protocols}
+ if identifier == "INTEGRATION-ENTRYPOINTS":
+ good = value == dict(
+ entrypoints=[
+ dict(
+ protocol=p,
+ http_forward=True,
+ http_connect=True,
+ tun_tcp=True,
+ tun_udp=True,
+ tun_dns=True,
+ )
+ for p in protocols
+ ]
+ )
+ elif identifier == "INTEGRATION-GRAPH":
+ good = value == dict(
+ protocols=protocols,
+ nested_select=True,
+ old_transport_snapshot=True,
+ cold_reject=True,
+ direct=True,
+ unselected_cycle=True,
+ no_fallback=True,
+ )
+ elif identifier == "INTEGRATION-DNS-MEASURE":
+ good = value == dict(
+ protocols=protocols,
+ controlled_dns_via_proxy=True,
+ ip_rule_consumer=True,
+ node_measure=True,
+ group_measure_rejected=True,
+ )
+ elif identifier == "INTEGRATION-FAILURES":
+ expected = {
+ (suite, p): 1
+ for suite in (
+ identifier,
+ "INTEGRATION-FAILURES-AUTH",
+ "INTEGRATION-FAILURES-SOURCE",
+ )
+ for p in protocols
+ }
+ good = value == dict(
+ protect_rejected=protocols,
+ auth_rejected=protocols,
+ certificate_pin_rejected=[
+ "anytls",
+ "trojan",
+ "vmess",
+ "vless",
+ "hysteria2",
+ ],
+ source_and_oversize_isolated=protocols,
+ cancel_preserves_sibling=protocols,
+ no_origin_bytes=True,
+ stop_idle=True,
+ )
+ good &= all(
+ idle_resources(e.get("resources"))
+ for e in events
+ if e.get("status") == "PASS"
+ and e.get("suite") != "INTEGRATION-FAILURES-AUTH"
+ )
+ elif identifier in {"INTEGRATION-SS-ALGORITHMS", "INTEGRATION-SS-EIH"}:
+ eih = identifier == "INTEGRATION-SS-EIH"
+ ciphers = ["2022-blake3-aes-128-gcm", "2022-blake3-aes-256-gcm"] + (
+ [] if eih else ["2022-blake3-chacha20-poly1305"]
+ )
+ expected = {(identifier, c): 1 for c in ciphers} | {
+ ("INTEGRATION-BASE", "tcp_10mib_both_directions"): 8 if eih else 9
+ }
+ good = value == (
+ dict(
+ native_terminal_eih=[
+ dict(
+ cipher=c,
+ identity_depth=1,
+ outer_families=2,
+ tcp_targets=2,
+ tcp_bytes_each_direction=41943040,
+ udp_targets=2,
+ udp_packets=2000,
+ wrong_identity_rejected=True,
+ wrong_user_rejected=True,
+ )
+ for c in ciphers
+ ],
+ arbitrary_relay_claim=False,
+ )
+ if eih
+ else dict(
+ algorithms=[
+ dict(
+ cipher=c,
+ tcp_targets=3,
+ tcp_bytes_each_direction=31457280,
+ udp_targets=3,
+ udp_packets=1500,
+ wrong_key_rejected=True,
+ )
+ for c in ciphers
+ ]
+ )
+ )
+ elif identifier == "INTEGRATION-LIFECYCLE":
+ expected = {(identifier, "stop_and_remain_quiet"): 100}
+ good = lifetimes(value, events)
+ else:
+ name = (
+ "forty_flows_same_session"
+ if identifier == "INTEGRATION-REBUILD"
+ else "mixed_forty_flows"
+ )
+ expected = {(identifier, name): 1}
+ passes = [e for e in events if e.get("status") == "PASS"]
+ good = len(passes) == 1 and (
+ rebuild(value, passes[0])
+ if identifier == "INTEGRATION-REBUILD"
+ else soak(
+ value,
+ passes[0],
+ read_events(directory / (identifier + "-observations.json.jsonl")),
+ )
+ )
+ return bool(good and assertions_pass(events, expected))
diff --git a/scripts/src/vcore_scripts/protocol_integration_local.py b/scripts/src/vcore_scripts/protocol_integration_local.py
new file mode 100644
index 0000000..3d91d8f
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_integration_local.py
@@ -0,0 +1,98 @@
+"""Explicit memory-only/build commands; never run historical host-server suites."""
+
+from __future__ import annotations
+
+import sys
+
+from .core_checks import commands as core_commands
+from .protocol_hysteria2_acceptance import commands as hysteria2_commands
+
+
+def commands(identifier):
+ if identifier in {
+ "INTEGRATION-DEBUG",
+ "INTEGRATION-RELEASE",
+ "INTEGRATION-FEATURES",
+ }:
+ return core_commands(identifier.removeprefix("INTEGRATION-").lower())
+ if identifier == "INTEGRATION-QUALITY":
+ return hysteria2_commands("HYSTERIA2-QUALITY") + [
+ ["vcore-scripts", "check", "protocol-coverage", "--catalog-only"],
+ ["vcore-scripts", "build", "apple"],
+ ["vcore-scripts", "build", "android"],
+ ]
+ if identifier == "INTEGRATION-SCRIPTS":
+ return [
+ [
+ sys.executable,
+ "-m",
+ "vcore_scripts.protocol_script_tests",
+ "{output}/script-tests.json",
+ ]
+ ]
+ return []
+
+
+def passed(identifier, records, events, script=None):
+ from .protocol_hysteria2_catalog import CFG, UNIT, assertions_pass
+ from .protocol_integration_catalog import PROTOCOLS
+ from .protocol_security_units import TESTS
+
+ good = bool(records) and all(
+ type(r.get("exit_code")) is int
+ and r["exit_code"] == 0
+ and r.get("cleanup") is True
+ for r in records
+ )
+ if identifier in {"INTEGRATION-DEBUG", "INTEGRATION-RELEASE"}:
+ expected = {
+ ("SECURITY-CONFIG-TLS", name): 1
+ for names in TESTS.values()
+ for name in names
+ }
+ expected.update({("HYSTERIA2-CFG", name): 1 for name in CFG})
+ expected.update({("HYSTERIA2-UNIT", name): 1 for name in UNIT})
+ expected.update({("INTEGRATION-FEATURE", name): 1 for name in PROTOCOLS})
+ expected[("INTEGRATION-ADAPTER", "growing_caller_buffer")] = 1
+ expected[("INTEGRATION-ADAPTER", "server_first_buffered_upstream")] = 1
+ expected[("INTEGRATION-ADAPTER", "hysteria2_fragment_id_reuse")] = 1
+ selected = [
+ e
+ for e in events
+ if e.get("suite")
+ in {
+ "SECURITY-CONFIG-TLS",
+ "HYSTERIA2-CFG",
+ "HYSTERIA2-UNIT",
+ "INTEGRATION-FEATURE",
+ "INTEGRATION-ADAPTER",
+ }
+ ]
+ good &= assertions_pass(selected, expected) and all(
+ e.get("status") in {"BEGIN", "PASS"} for e in events
+ )
+ if identifier == "INTEGRATION-FEATURES":
+ good &= assertions_pass(
+ [e for e in events if e.get("suite") == "INTEGRATION-FEATURE"],
+ {("INTEGRATION-FEATURE", p): 7 for p in PROTOCOLS},
+ )
+ if identifier == "INTEGRATION-SCRIPTS":
+ rows = (script or {}).get("cases", [])
+ names = [r.get("test") for r in rows]
+ required = {
+ "test_protocol_integration.IntegrationAcceptanceTest." + name
+ for name in (
+ "test_integration_consumer_results_keep_the_manifest_scope",
+ "test_pair_evidence_requires_each_real_path_and_original_assertions",
+ "test_list_contains_all_ordered_pairs_and_remaining_gates",
+ "test_pressure_evidence_is_recomputed_not_inferred",
+ "test_native_source_identity_and_cleanup_are_required",
+ )
+ }
+ good &= (
+ bool(rows)
+ and len(names) == len(set(names)) == (script or {}).get("tests_run")
+ and required <= set(names)
+ and all(r.get("status") == "PASS" for r in rows)
+ )
+ return bool(good)
diff --git a/scripts/src/vcore_scripts/protocol_integration_metrics.py b/scripts/src/vcore_scripts/protocol_integration_metrics.py
new file mode 100644
index 0000000..c0b5e26
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_integration_metrics.py
@@ -0,0 +1,220 @@
+"""Recompute lifecycle/pressure gates from bounded, persisted observations."""
+
+from __future__ import annotations
+
+from math import isfinite
+from statistics import median
+
+from .protocol_evidence import RESOURCE_KINDS, idle_resources
+
+NEW = ["trojan", "vmess", "vless", "hysteria2"]
+QUEUES = {
+ "socks_udp": 16,
+ "hysteria2_udp": 32,
+ "quic_incoming": 32,
+ "quic_outgoing": 32,
+}
+
+
+def integer(value, minimum=0):
+ return type(value) is int and value >= minimum
+
+
+def resources(value, *, active=False):
+ rows = value.get("counts", [])
+ if len(rows) != 8 or {r.get("kind") for r in rows} != RESOURCE_KINDS:
+ return False
+ if not all(
+ integer(r.get("current"))
+ and integer(r.get("peak"))
+ and r["current"] <= r["peak"]
+ for r in rows
+ ):
+ return False
+ counts = {r["kind"]: r["current"] for r in rows}
+ return not active or all(
+ counts[k] > 0 for k in ("task", "socket", "session", "association")
+ )
+
+
+def sample(value, *, active=True):
+ queues = value.get("queues", [])
+ return (
+ integer(value.get("heap_in_use"), 1)
+ and integer(value.get("rss_kib"), 1)
+ and integer(value.get("fd"), 1)
+ and resources(value.get("resources", {}), active=active)
+ and len(queues) == 4
+ and {q.get("kind"): q.get("capacity") for q in queues} == QUEUES
+ and all(
+ integer(q.get("peak"), 1) and q["peak"] <= q["capacity"] for q in queues
+ )
+ )
+
+
+def lifetimes(value, events):
+ cycles = value.get("cycles", [])
+ passes = [e for e in events if e.get("status") == "PASS"]
+ if value.get("count") != 100 or len(cycles) != 100 or len(passes) != 100:
+ return False
+ for index, (row, event) in enumerate(zip(cycles, passes, strict=True)):
+ stop = row.get("after_stop", {})
+ checkpoints = event.get("checkpoints", [])
+ mode = index % 5
+ retained = {0: 0, 1: 10, 2: 1, 3: 0, 4: 8}[mode]
+ if not (
+ row.get("cycle") == index
+ and row.get("protocol") == NEW[(index // 5) % 4]
+ and row.get("mode") == mode
+ and integer(row.get("baseline_fd"), 1)
+ and row.get("retained_fixture_fd") == retained
+ and integer(row.get("after_stop_fd"), 1)
+ and row["after_stop_fd"] <= row["baseline_fd"] + retained
+ and integer(row.get("final_fd"), 1)
+ and row["final_fd"] <= row["baseline_fd"]
+ and integer(row.get("stop_ms"))
+ and row["stop_ms"] < 5000
+ and isfinite(row.get("quiet_seconds", 0))
+ and row.get("quiet_seconds", 0) >= 5
+ and row.get("ports_rebound") is True
+ and idle_resources(stop)
+ and row.get("quiet") == stop == event.get("resources")
+ and len(checkpoints) == 4
+ and [p.get("phase") for p in checkpoints]
+ == ["baseline", "active", "after-stop", "quiet"]
+ and idle_resources(checkpoints[0].get("resources"))
+ and checkpoints[1].get("resources") == row.get("active")
+ and resources(row.get("active", {}))
+ and checkpoints[2].get("resources")
+ == stop
+ == checkpoints[3].get("resources")
+ ):
+ return False
+ if mode in (1, 4) and not resources(row["active"], active=True):
+ return False
+ return True
+
+
+def stopped(value, event):
+ cold, baseline = value.get("cold_fd"), value.get("baseline_fd")
+ row = value.get("stopped", {})
+ after, quiet = row.get("after_stop", {}), row.get("quiet", {})
+ return (
+ integer(cold, 1)
+ and integer(baseline, 1)
+ and 0 <= baseline - cold <= 2
+ and integer(row.get("stop_ms"))
+ and row["stop_ms"] < 5000
+ and isfinite(row.get("quiet_seconds", 0))
+ and row.get("quiet_seconds", 0) >= 5
+ and row.get("ports_rebound") is True
+ and sample(after, active=False)
+ and sample(quiet, active=False)
+ and idle_resources(after.get("resources"))
+ and quiet.get("resources") == after.get("resources") == event.get("resources")
+ and after["fd"] <= baseline
+ and quiet["fd"] <= baseline
+ )
+
+
+def setup(values):
+ return (
+ isinstance(values, list)
+ and len(values) == 40
+ and all(integer(v, 1) and v < 10_000_000 for v in values)
+ )
+
+
+def rebuild(value, event):
+ rows = value.get("cycles", [])
+ return (
+ value.get("count") == 100
+ and value.get("same_running_session") is True
+ and value.get("protocols") == NEW
+ and len(rows) == 100
+ and stopped(value, event)
+ and all(
+ row.get("generation") == i
+ and row.get("tcp") == row.get("udp") == 20
+ and row.get("per_protocol_tcp") == row.get("per_protocol_udp") == 5
+ and sample(row.get("active", {}))
+ and sample(row.get("after_clients", {}), active=False)
+ and setup(row.get("setup_us"))
+ and row.get("fault") == "owned-peer-connections-closed"
+ and row.get("new_clients") is True
+ for i, row in enumerate(rows)
+ )
+ )
+
+
+def soak(value, event, curve):
+ points, faults, switches = (
+ value.get("samples", []),
+ value.get("faults", []),
+ value.get("switches", []),
+ )
+ if not (
+ value.get("requested_seconds") == 1800
+ and 1800 <= value.get("seconds", 0) < 1860
+ and value.get("protocols") == NEW
+ and value.get("tcp") == value.get("udp") == 20
+ and value.get("per_protocol_tcp") == value.get("per_protocol_udp") == 5
+ and integer(value.get("waves"), 1)
+ and value.get("normal_verified_bytes") == value["waves"] * 20 * 2 * 2 * 257
+ and all(
+ value.get(k) == 0
+ for k in (
+ "normal_corruption",
+ "normal_misdirection",
+ "normal_unexpected_loss",
+ )
+ )
+ and len(points) >= 25
+ and points == curve
+ and 29 <= len(faults) <= 30
+ and len(switches) >= 1799
+ and all(i <= t < i + 5 for i, t in enumerate(switches, 1))
+ and all(
+ 60 * i <= row.get("start", 0) < 60 * i + 5
+ and row["start"] <= row.get("end", 0) < row["start"] + 10
+ and row.get("old_tcp_closed")
+ == row.get("new_tcp")
+ == row.get("new_udp")
+ == 20
+ and row.get("replay") is False
+ for i, row in enumerate(faults, 1)
+ )
+ and all(
+ sample(p) and 300 + 60 * i <= p.get("seconds", 0) < 310 + 60 * i
+ for i, p in enumerate(points)
+ )
+ and stopped(value, event)
+ and sample(value.get("active_end", {}))
+ and setup(value.get("first_setup_us"))
+ and setup(value.get("last_setup_us"))
+ ):
+ return False
+ first_setup, last_setup = (
+ int(median(value[k])) for k in ("first_setup_us", "last_setup_us")
+ )
+ early, late = points[:10], points[-10:]
+ first, last = (
+ int(median(p["heap_in_use"] for p in rows)) for rows in (early, late)
+ )
+ allowed = max(1024 * 1024, first // 20)
+
+ def counts(rows, kind):
+ return max(
+ next(r["current"] for r in p["resources"]["counts"] if r["kind"] == kind)
+ for p in rows
+ )
+
+ return (
+ first_setup == value.get("first_setup_median_us")
+ and last_setup == value.get("last_setup_median_us") <= 2 * first_setup
+ and value.get("heap")
+ == dict(early_median=first, late_median=last, allowed_growth=allowed)
+ and last <= first + allowed
+ and all(counts(late, kind) <= counts(early, kind) for kind in RESOURCE_KINDS)
+ and max(p["fd"] for p in late) <= max(p["fd"] for p in early)
+ )
diff --git a/scripts/src/vcore_scripts/protocol_integration_native.py b/scripts/src/vcore_scripts/protocol_integration_native.py
new file mode 100644
index 0000000..e74f5d0
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_integration_native.py
@@ -0,0 +1,305 @@
+"""Seven-protocol integration with owned official peers and container origins."""
+
+from __future__ import annotations
+
+import base64
+import contextlib
+import json
+import os
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+
+from .builds import CORE_DIR
+from .mihomo_isolation import exclusive_run
+from .mihomo_release import download_mihomo
+from .native_release import download_native
+from .protocol_containers import ContainerLab, command, frozen_image
+from .protocol_fixtures import certificates
+from .protocol_inputs import redact, sha256, source_identity
+from .protocol_integration_catalog import PAIRS
+from .protocol_peers import run_command
+
+
+def peer_configuration(protocol, server, origin, directory, *, certificate=None):
+ cert, key, pin = certificate or certificates(directory)
+ listener = dict(name="integration", type=protocol, listen="::", port=23000)
+ node = dict(name="peer", type=protocol, server=server, port=23000, udp=True)
+ password = "synthetic-integration-fixture"
+ identity = "07070707-0707-0707-0707-070707070707"
+ if protocol == "socks5":
+ listener.update(
+ type="socks", udp=True, users=[dict(username="fixture", password=password)]
+ )
+ node.update(username="fixture", password=password)
+ elif protocol == "ss":
+ password = base64.b64encode(bytes([7]) * 16).decode()
+ cipher = "2022-blake3-aes-128-gcm"
+ listener.update(type="shadowsocks", udp=True, cipher=cipher, password=password)
+ node.update(cipher=cipher, password=password)
+ elif protocol in {"trojan", "anytls", "hysteria2"}:
+ node.update(password=password, sni="localhost", fingerprint=pin)
+ listener["users"] = (
+ [dict(username="fixture", password=password)]
+ if protocol == "trojan"
+ else {"fixture": password}
+ )
+ else:
+ node.update(uuid=identity, tls=True, servername="localhost", fingerprint=pin)
+ listener["users"] = [dict(username="fixture", uuid=identity)]
+ if protocol == "vmess":
+ node.update(cipher="auto", alterId=0)
+ listener["users"][0]["alterId"] = 0
+ node["packet-encoding"] = "xudp"
+ if protocol not in {"socks5", "ss"}:
+ listener.update(
+ certificate=f"/data/fixture/{cert.name}",
+ **{"private-key": f"/data/fixture/{key.name}"},
+ )
+ return node, {
+ "socks-port": 23999,
+ "allow-lan": True,
+ "bind-address": "*",
+ "ipv6": True,
+ "log-level": "silent",
+ "hosts": {"vcore-fixture.test": origin},
+ "listeners": [listener],
+ "rules": ["MATCH,DIRECT"],
+ }
+
+
+def rust_command(consumer="ordered_pair"):
+ return [
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ "vless_public",
+ f"integration::{consumer}",
+ "--",
+ "--exact",
+ "--ignored",
+ "--nocapture",
+ ]
+
+
+def run(
+ output: Path, selected, *, supplied=None, consumer="ordered_pair", domain_peer=None
+):
+ if (
+ not selected
+ or len(selected) != len(set(selected))
+ or not set(selected) <= PAIRS.keys()
+ ):
+ raise ValueError("invalid INTEGRATION pair selection")
+ output = output.resolve()
+ if not output.is_relative_to((CORE_DIR / "target/interop/runs").resolve()):
+ raise ValueError(
+ "INTEGRATION evidence must stay inside the owned run directory"
+ )
+ output.mkdir(parents=True, exist_ok=False)
+ report = dict(
+ stage="INTEGRATION",
+ scope="ordered-pair-subset" if consumer == "ordered_pair" else "diagnostic",
+ source=source_identity(),
+ status="NOT RUN",
+ cases=[],
+ peers={},
+ isolation={},
+ )
+ try:
+ if supplied is None:
+ identity = {}
+ binary = download_mihomo(
+ "linux-arm64", directory=output / "binaries", identity=identity
+ )
+ else:
+ binary, identity = supplied
+ if sha256(binary) != identity["binary_sha256"]:
+ raise RuntimeError("INTEGRATION native peer identity mismatch")
+ report["peers"]["M"] = identity
+ if any(PAIRS[key][1] == "trojan" for key in selected):
+ if domain_peer is None:
+ artifact = download_native(
+ "XR", output / "binary-xray", "linux-arm64", defer_version=True
+ )
+ domain_peer = (artifact.binary, artifact.identity)
+ if sha256(domain_peer[0]) != domain_peer[1]["binary_sha256"]:
+ raise RuntimeError("INTEGRATION domain terminal identity mismatch")
+ report["peers"]["XR"] = domain_peer[1]
+ lab = ContainerLab(report["isolation"], mtu=1500)
+ for index, identifier in enumerate(selected):
+ first_kind, last_kind = PAIRS[identifier]
+ print(f"INTEGRATION: {identifier}", flush=True)
+ with tempfile.TemporaryDirectory(
+ prefix="private-", dir=output
+ ) as temporary:
+ root = Path(temporary)
+ with contextlib.ExitStack() as stack:
+ origin_dir = root / "origin"
+ origin_dir.mkdir()
+ shutil.copyfile(
+ Path(__file__).with_name("container_udp_origin.py"),
+ origin_dir / "origin.py",
+ )
+ origin = lab.start(
+ stack,
+ origin_dir,
+ f"{index}-origin",
+ [
+ "env",
+ "VCORE_ISOLATED_ORIGIN=1",
+ "python",
+ "-B",
+ "/data/fixture/origin.py",
+ ],
+ )
+ origin.release()
+ origin.wait_tcp(24000)
+ fixture = dict(
+ isolation="containers",
+ origin_control=f"{origin.ipv4}:24000",
+ origin_ipv4=origin.ipv4,
+ origin_ipv6=origin.ipv6,
+ data_dir=str(root / "core"),
+ )
+ for role, protocol in (("first", first_kind), ("last", last_kind)):
+ directory = root / role
+ directory.mkdir()
+ shutil.copy2(binary, directory / "peer")
+ peer = lab.start(
+ stack,
+ directory,
+ f"{index}-{role}",
+ [
+ "/data/fixture/peer",
+ "-d",
+ "/data",
+ "-f",
+ "/data/fixture/config.json",
+ ],
+ )
+ identity["version"] = command(
+ "exec", peer.name, "/data/fixture/peer", "-v"
+ ).strip()
+ if (
+ command(
+ "exec", peer.name, "sha256sum", "/data/fixture/peer"
+ ).split()[0]
+ != identity["binary_sha256"]
+ ):
+ raise RuntimeError(
+ "INTEGRATION container binary differs from download"
+ )
+ node, config = peer_configuration(
+ protocol, peer.ipv4, origin.ipv4, directory
+ )
+ (directory / "config.json").write_text(json.dumps(config))
+ fixture[role], fixture[role + "_ipv6"] = node, peer.ipv6
+ peer.release()
+ peer.wait_tcp(23999)
+ if last_kind == "trojan":
+ from .protocol_fixtures import trojan_peer_config as peer_config
+
+ directory = root / "domain"
+ directory.mkdir()
+ shutil.copy2(domain_peer[0], directory / "peer")
+ peer = lab.start(
+ stack,
+ directory,
+ f"{index}-domain",
+ [
+ "/data/fixture/peer",
+ "run",
+ "-c",
+ "/data/fixture/config.json",
+ ],
+ )
+ domain_peer[1]["version"] = command(
+ "exec", peer.name, "/data/fixture/peer", "version"
+ ).strip()
+ if (
+ command(
+ "exec", peer.name, "sha256sum", "/data/fixture/peer"
+ ).split()[0]
+ != domain_peer[1]["binary_sha256"]
+ ):
+ raise RuntimeError(
+ "INTEGRATION domain container binary identity mismatch"
+ )
+ certificate = certificates(directory)
+ node, _ = peer_configuration(
+ "trojan",
+ peer.ipv4,
+ origin.ipv4,
+ directory,
+ certificate=certificate,
+ )
+ cert, key, _ = certificate
+ config = peer_config(
+ "XR",
+ "tcp",
+ 23000,
+ node["password"],
+ f"/data/fixture/{cert.name}",
+ f"/data/fixture/{key.name}",
+ )
+ config["inbounds"][0]["listen"] = "::"
+ config["dns"]["hosts"] = {"vcore-fixture.test": origin.ipv4}
+ (directory / "config.json").write_text(json.dumps(config))
+ fixture["domain_last"], fixture["domain_last_ipv6"] = (
+ node,
+ peer.ipv6,
+ )
+ peer.release()
+ peer.wait_tcp(23000)
+ path = root / "fixture.json"
+ path.write_text(json.dumps(fixture))
+ events = output / (identifier + "-events.jsonl")
+ observations = output / (identifier + "-observations.json")
+ env = dict(
+ os.environ,
+ VCORE_VLESS_INPUT=str(path),
+ VCORE_PROTOCOL_STAGE="INTEGRATION",
+ VCORE_CASE_EVENTS=str(events),
+ VCORE_INTEGRATION_OBSERVATIONS=str(observations),
+ )
+ argv = rust_command(consumer)
+ result = run_command(argv, cwd=CORE_DIR, env=env, timeout=300)
+ (output / (identifier + ".log")).write_text(
+ redact(result.stdout.decode(errors="replace"))
+ )
+ report["cases"].append(
+ dict(
+ case_id=identifier,
+ command=argv,
+ exit_code=result.returncode,
+ command_cleanup=result.cleanup,
+ seconds=result.seconds,
+ )
+ )
+ if result.returncode != 0 or not result.cleanup:
+ raise RuntimeError("INTEGRATION ordered-pair consumer failed")
+ report["status"] = "PASS"
+ except BaseException as error:
+ report.update(status="FAIL", failure_kind=type(error).__name__)
+ raise
+ finally:
+ report["source_unchanged"] = source_identity() == report["source"]
+ report["cleanup"] = all(
+ peer.get("joined") is True for peer in report["isolation"].get("peers", [])
+ )
+ if not report["cleanup"] or not report["source_unchanged"]:
+ report["status"] = "FAIL"
+ (output / "integration-native.json").write_text(
+ json.dumps(report, indent=2) + "\n"
+ )
+ return report
+
+
+if __name__ == "__main__":
+ output = Path(sys.argv[1]).resolve()
+ with exclusive_run(), frozen_image(None):
+ run(output, sys.argv[2:] or list(PAIRS))
diff --git a/scripts/src/vcore_scripts/protocol_integration_shared.py b/scripts/src/vcore_scripts/protocol_integration_shared.py
new file mode 100644
index 0000000..03f7174
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_integration_shared.py
@@ -0,0 +1,91 @@
+"""Frozen strongly-coupled TLS/transport and uninterrupted hopping regressions."""
+
+from __future__ import annotations
+
+from .protocol_evidence import read_json
+from .protocol_integration_checks import envelope
+from .protocol_security_acceptance import CHECKERS, REPORTS
+from .protocol_security_catalog import groups
+
+SHARED = (
+ "SECURITY-SHARED-NONE",
+ "SECURITY-SHARED-CHROME",
+ "SECURITY-SHARED-XHTTP",
+ "SECURITY-HYBRID-RETAINED",
+ "SECURITY-JLS-RETAINED",
+ "SECURITY-ECH-CHROME",
+ "SECURITY-ECH-ENCRYPTION-NATIVE-0RTT-MIXED",
+ "SECURITY-JLS-ENCRYPTION-NATIVE-0RTT-MIXED",
+ "SECURITY-HYBRID-ENCRYPTION-NATIVE-0RTT-MIXED",
+)
+HOPS = (
+ "HYSTERIA2-HOP-V4-PLAIN-FIXED",
+ "HYSTERIA2-HOP-V4-OBFS-RANDOM",
+ "HYSTERIA2-HOP-V6-PLAIN-RANDOM",
+ "HYSTERIA2-HOP-V6-OBFS-FIXED",
+)
+
+
+def shared_run(directory, supplied):
+ from .protocol_reality_hybrid import run as hybrid
+ from .protocol_vless_container import run as vless
+ from .protocol_xhttp_fields import run as xhttp
+
+ catalog = groups()
+ for name in SHARED:
+ print("INTEGRATION shared: " + name, flush=True)
+ group = catalog[name]
+ options = {k: v for k, v in group.items() if k not in {"rows", "runner"}}
+ if group["runner"] == "xhttp":
+ options["selected"] = list(options["jobs"])
+ {"vless": vless, "xhttp": xhttp, "hybrid": hybrid}[group["runner"]](
+ directory / name, supplied=supplied, **options
+ )
+
+
+def shared_pass(directory, peers, source, digest):
+ catalog = groups()
+ for name in SHARED:
+ group = catalog[name]
+ root = directory / name
+ report = read_json(root / REPORTS[group["runner"]])
+ if not envelope(report, peers, source, digest) or not CHECKERS[group["runner"]](
+ group, report, root
+ ):
+ return False
+ return True
+
+
+def hops_run(directory, supplied):
+ from .protocol_hysteria2_catalog import H
+ from .protocol_hysteria2_hop import run
+
+ for name in HOPS:
+ print("INTEGRATION uninterrupted: " + name, flush=True)
+ run(directory / name, supplied=supplied, **H[name])
+
+
+def hops_pass(directory, peers, source, digest):
+ from .protocol_hysteria2_acceptance import native_result
+ from .protocol_hysteria2_catalog import definitions
+
+ catalog = {c["case_id"]: c for c in definitions()}
+ prep = read_json(directory.parent / "package-preparation.json")
+ if not (
+ prep.get("firewall_packages")
+ and prep.get("peers")
+ and all(p.get("joined") is True for p in prep["peers"])
+ and prep.get("image_digest") == digest
+ ):
+ return False
+ for name in HOPS:
+ root = directory / name
+ report = read_json(root / "report.json")
+ if not (
+ envelope(report, peers, source, digest, single="H")
+ and native_result(catalog[name], report, root)["status"] == "PASS"
+ and report["isolation"].get("firewall_packages")
+ == prep["firewall_packages"]
+ ):
+ return False
+ return True
diff --git a/scripts/src/vcore_scripts/protocol_integration_suite.py b/scripts/src/vcore_scripts/protocol_integration_suite.py
new file mode 100644
index 0000000..c7e99ea
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_integration_suite.py
@@ -0,0 +1,351 @@
+"""INTEGRATION public-runtime gates against seven listeners in an owned native peer."""
+
+from __future__ import annotations
+
+import base64
+import contextlib
+import json
+import os
+import re
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+
+from .builds import CORE_DIR
+from .mihomo_isolation import exclusive_run
+from .mihomo_release import download_mihomo
+from .native_release import download_native
+from .protocol_containers import ContainerLab, command, frozen_image
+from .protocol_fixtures import certificates
+from .protocol_inputs import redact, sha256, source_identity
+from .protocol_integration_catalog import PROTOCOLS
+from .protocol_integration_native import peer_configuration, rust_command
+from .protocol_peers import run_command
+
+CONSUMERS = {
+ "INTEGRATION-ENTRYPOINTS": "entrypoints",
+ "INTEGRATION-GRAPH": "graph",
+ "INTEGRATION-DNS-MEASURE": "dns_measure",
+ "INTEGRATION-RESOURCE-TRACER": "resource_tracer",
+ "INTEGRATION-LIFECYCLE": "lifecycle::public_lifetimes",
+ "INTEGRATION-LIFECYCLE-TRACER": "lifecycle::lifecycle_tracer",
+ "INTEGRATION-REBUILD": "pressure::rebuild",
+ "INTEGRATION-REBUILD-TRACER": "pressure::rebuild_tracer",
+ "INTEGRATION-SOAK": "pressure::soak",
+ "INTEGRATION-SOAK-TRACER": "pressure::soak_tracer",
+ "INTEGRATION-SS-ALGORITHMS": "shadowsocks::algorithms",
+ "INTEGRATION-SS-EIH": "shadowsocks::eih",
+ "INTEGRATION-FAILURES": "connector::protect_failure",
+}
+
+
+def run(output: Path, selected, *, supplied=None):
+ if (
+ not selected
+ or len(selected) != len(set(selected))
+ or not set(selected) <= CONSUMERS.keys()
+ ):
+ raise ValueError("invalid INTEGRATION public gate selection")
+ output = output.resolve()
+ if not output.is_relative_to((CORE_DIR / "target/interop/runs").resolve()):
+ raise ValueError(
+ "INTEGRATION evidence must stay inside the owned run directory"
+ )
+ output.mkdir(parents=True, exist_ok=False)
+ report = dict(
+ stage="INTEGRATION",
+ scope="public-runtime-subset",
+ source=source_identity(),
+ status="NOT RUN",
+ cases=[],
+ peers={},
+ isolation={},
+ )
+ try:
+ if supplied is None:
+ identity = {}
+ binary = download_mihomo(
+ "linux-arm64", directory=output / "binaries", identity=identity
+ )
+ else:
+ binary, identity = supplied
+ if sha256(binary) != identity["binary_sha256"]:
+ raise RuntimeError("INTEGRATION native peer identity mismatch")
+ report["peers"]["M"] = identity
+ lab = ContainerLab(report["isolation"], mtu=1500)
+ with tempfile.TemporaryDirectory(prefix="private-", dir=output) as temporary:
+ root = Path(temporary)
+ with contextlib.ExitStack() as stack:
+ origin_dir = root / "origin"
+ origin_dir.mkdir()
+ shutil.copyfile(
+ Path(__file__).with_name("container_udp_origin.py"),
+ origin_dir / "origin.py",
+ )
+ origin = lab.start(
+ stack,
+ origin_dir,
+ "origin",
+ [
+ "env",
+ "VCORE_ISOLATED_ORIGIN=1",
+ "VCORE_ORIGIN_PROFILE=INTEGRATION",
+ "python",
+ "-B",
+ "/data/fixture/origin.py",
+ ],
+ )
+ origin.release()
+ origin.wait_tcp(24000)
+ upstream_dir = root / "upstream"
+ upstream_dir.mkdir()
+ shutil.copy2(binary, upstream_dir / "peer")
+ upstream = lab.start(
+ stack,
+ upstream_dir,
+ "upstream",
+ [
+ "/data/fixture/peer",
+ "-d",
+ "/data",
+ "-f",
+ "/data/fixture/config.json",
+ ],
+ )
+ hop, upstream_config = peer_configuration(
+ "socks5", upstream.ipv4, origin.ipv4, upstream_dir
+ )
+ hop["name"] = "hop"
+ (upstream_dir / "config.json").write_text(json.dumps(upstream_config))
+ upstream.release()
+ upstream.wait_tcp(23999)
+ if (
+ command(
+ "exec", upstream.name, "sha256sum", "/data/fixture/peer"
+ ).split()[0]
+ != identity["binary_sha256"]
+ ):
+ raise RuntimeError(
+ "INTEGRATION upstream binary differs from download"
+ )
+ directory = root / "native"
+ directory.mkdir()
+ shutil.copy2(binary, directory / "peer")
+ peer = lab.start(
+ stack,
+ directory,
+ "native",
+ [
+ "/data/fixture/peer",
+ "-d",
+ "/data",
+ "-f",
+ "/data/fixture/config.json",
+ ],
+ )
+ identity["version"] = command(
+ "exec", peer.name, "/data/fixture/peer", "-v"
+ ).strip()
+ if (
+ command(
+ "exec", peer.name, "sha256sum", "/data/fixture/peer"
+ ).split()[0]
+ != identity["binary_sha256"]
+ ):
+ raise RuntimeError(
+ "INTEGRATION container binary differs from download"
+ )
+ certificate = certificates(directory)
+ nodes, listeners = {}, []
+ config = None
+ for index, protocol in enumerate(PROTOCOLS):
+ node, current = peer_configuration(
+ protocol,
+ peer.ipv4,
+ origin.ipv4,
+ directory,
+ certificate=certificate,
+ )
+ port = 23000 + index
+ node["port"] = port
+ current["listeners"][0].update(name=protocol, port=port)
+ nodes[protocol] = node
+ listeners.extend(current["listeners"])
+ config = current
+ ss_nodes = [nodes["ss"].copy()]
+ for index, cipher in enumerate(
+ ("2022-blake3-aes-256-gcm", "2022-blake3-chacha20-poly1305")
+ ):
+ node = nodes["ss"].copy()
+ node.update(
+ port=23010 + index,
+ cipher=cipher,
+ password=base64.b64encode(bytes([7]) * 32).decode(),
+ )
+ listeners.append(
+ dict(
+ name=cipher,
+ type="shadowsocks",
+ listen="::",
+ port=node["port"],
+ cipher=cipher,
+ password=node["password"],
+ udp=True,
+ )
+ )
+ ss_nodes.append(node)
+ config.update(
+ listeners=listeners,
+ **{
+ "external-controller": "0.0.0.0:23998",
+ "secret": "synthetic-integration-control",
+ },
+ )
+ (directory / "config.json").write_text(json.dumps(config))
+ peer.release()
+ peer.wait_tcp(23999)
+ fixture = dict(
+ isolation="containers",
+ origin_control=f"{origin.ipv4}:24000",
+ origin_ipv4=origin.ipv4,
+ origin_ipv6=origin.ipv6,
+ nodes=nodes,
+ ss_nodes=ss_nodes,
+ hop=hop,
+ server_ipv6=peer.ipv6,
+ peer_controller=f"{peer.ipv4}:23998",
+ data_dir=str(root / "core"),
+ )
+ if "INTEGRATION-SS-EIH" in selected:
+ artifact = download_native(
+ "SS", output / "binaries-ss", "linux-arm64", defer_version=True
+ )
+ ss_dir = root / "ssserver"
+ ss_dir.mkdir()
+ shutil.copy2(artifact.binary, ss_dir / "ssserver")
+ ss = lab.start(
+ stack,
+ ss_dir,
+ "ssserver",
+ ["/data/fixture/ssserver", "-c", "/data/fixture/config.json"],
+ )
+ artifact.identity["version"] = command(
+ "exec", ss.name, "/data/fixture/ssserver", "--version"
+ ).strip()
+ if (
+ command(
+ "exec", ss.name, "sha256sum", "/data/fixture/ssserver"
+ ).split()[0]
+ != artifact.identity["binary_sha256"]
+ ):
+ raise RuntimeError("INTEGRATION SS binary identity mismatch")
+ report["peers"]["SS"] = artifact.identity
+ servers, eih_nodes = [], []
+ for index, length in enumerate((16, 32)):
+ cipher = f"2022-blake3-aes-{length * 8}-gcm"
+ identity_key, user_key = [
+ base64.b64encode(bytes([v]) * length).decode()
+ for v in (9, 8)
+ ]
+ port = 23020 + index
+ servers.append(
+ dict(
+ server="::",
+ server_port=port,
+ method=cipher,
+ password=identity_key,
+ users=[dict(name="fixture", password=user_key)],
+ mode="tcp_and_udp",
+ )
+ )
+ eih_nodes.append(
+ dict(
+ name="peer",
+ type="ss",
+ server=ss.ipv4,
+ port=port,
+ cipher=cipher,
+ password=f"{identity_key}:{user_key}",
+ udp=True,
+ )
+ )
+ (ss_dir / "config.json").write_text(
+ json.dumps(
+ dict(
+ servers=servers,
+ outbound_udp_allow_fragmentation=True,
+ inbound_udp_allow_fragmentation=True,
+ )
+ )
+ )
+ report["ssserver_policy"] = dict(
+ outbound_udp_allow_fragmentation=True,
+ inbound_udp_allow_fragmentation=True,
+ guest_mtu=1500,
+ )
+ ss.release()
+ ss.wait_tcp(23020)
+ fixture["eih_nodes"] = eih_nodes
+ fixture["eih_ipv6"] = ss.ipv6
+ path = root / "fixture.json"
+ path.write_text(json.dumps(fixture))
+ for identifier in selected:
+ print(f"INTEGRATION: {identifier}", flush=True)
+ env = dict(
+ os.environ,
+ VCORE_VLESS_INPUT=str(path),
+ VCORE_PROTOCOL_STAGE="INTEGRATION",
+ VCORE_CASE_EVENTS=str(output / (identifier + "-events.jsonl")),
+ VCORE_INTEGRATION_OBSERVATIONS=str(
+ output / (identifier + "-observations.json")
+ ),
+ )
+ argv = rust_command(CONSUMERS[identifier])
+ result = run_command(argv, cwd=CORE_DIR, env=env, timeout=3600)
+ (output / (identifier + ".log")).write_text(
+ redact(result.stdout.decode(errors="replace"))
+ )
+ report["cases"].append(
+ dict(
+ case_id=identifier,
+ command=argv,
+ exit_code=result.returncode,
+ command_cleanup=result.cleanup,
+ seconds=result.seconds,
+ )
+ )
+ if "INTEGRATION-SS-EIH" in selected:
+ # The follow-log owner buffers while live; snapshot via
+ # the CLI so a short failed run retains real diagnostics.
+ text = command("logs", ss.name)
+ for server in servers:
+ for key in (
+ server["password"],
+ server["users"][0]["password"],
+ ):
+ text = text.replace(key, "")
+ text = re.sub(r"(?:\d{1,3}\.){3}\d{1,3}", "", text)
+ (output / "ssserver.log").write_text(redact(text))
+ if result.returncode != 0 or not result.cleanup:
+ raise RuntimeError("INTEGRATION public-runtime consumer failed")
+ report["status"] = "PASS"
+ except BaseException as error:
+ report.update(status="FAIL", failure_kind=type(error).__name__)
+ raise
+ finally:
+ report["source_unchanged"] = source_identity() == report["source"]
+ report["cleanup"] = all(
+ peer.get("joined") is True for peer in report["isolation"].get("peers", [])
+ )
+ if not report["cleanup"] or not report["source_unchanged"]:
+ report["status"] = "FAIL"
+ (output / "integration-suite.json").write_text(
+ json.dumps(report, indent=2) + "\n"
+ )
+ return report
+
+
+if __name__ == "__main__":
+ with exclusive_run(), frozen_image(None):
+ run(Path(sys.argv[1]), sys.argv[2:] or list(CONSUMERS))
diff --git a/scripts/src/vcore_scripts/protocol_jls.py b/scripts/src/vcore_scripts/protocol_jls.py
new file mode 100644
index 0000000..0a160aa
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_jls.py
@@ -0,0 +1,104 @@
+"""JLS public consumers against official latest Mihomo in isolated containers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def catalog():
+ cases = {}
+
+ def add(mode, suffix, test):
+ cases[f"SECURITY-JLS-{mode.removesuffix('-tls').upper()}-{suffix}"] = (
+ "M",
+ mode,
+ True,
+ test,
+ )
+
+ modes = (
+ "tcp-tls",
+ "ws-tls",
+ "upgrade-tls",
+ "upgrade-fast-tls",
+ "grpc-tls",
+ ) + tuple(
+ f"xhttp-{mode}{version}"
+ for mode in (
+ "stream-one",
+ "stream-up",
+ "packet-up",
+ "stream-up-download",
+ "packet-up-download",
+ )
+ for version in ("", "-h1")
+ )
+ for mode in modes:
+ add(mode, "BASE", "public_base")
+ add(mode, "CLOSE", "native_mihomo_close_alignment")
+ for mode in (
+ "tcp-tls",
+ "ws-tls",
+ "grpc-tls",
+ "xhttp-stream-up-download",
+ "xhttp-stream-up-download-h1",
+ ):
+ add(mode, "AUTH", "native_jls_fail_closed")
+ for mode in modes:
+ if "download" in mode:
+ add(mode, "IDENTITY", "public_jls_download_identity")
+ for mode in ("tcp-tls", "grpc-tls"):
+ for suffix, test in (
+ ("GRAPH", "runtime::public_graph"),
+ ("IPV6", "runtime::public_ipv6_and_gates"),
+ ("ENTRYPOINTS", "runtime::public_entrypoints"),
+ ("UDP-ISOLATION", "runtime::public_udp_isolation"),
+ ):
+ add(mode, suffix, test)
+ for mode in ("grpc-tls", "xhttp-stream-up-download"):
+ add(mode, "LIFE", "runtime::public_lifecycle")
+ add(mode, "OWNED", "runtime::owned_resources")
+ return cases
+
+
+def configuration(node, peer, origin, mode):
+ credentials = dict(username="synthetic-jls-user", password="synthetic-jls-password")
+ download = dict(
+ username="synthetic-download-user", password="synthetic-download-password"
+ )
+ node.pop("fingerprint", None)
+ node["jls-opts"] = credentials
+ if mode.endswith("-h1"):
+ node["alpn"] = ["http/1.1"]
+ for listener in peer["listeners"]:
+ listener.pop("certificate", None)
+ listener.pop("private-key", None)
+ listener["jls-config"] = dict(
+ enable=True,
+ sni="localhost",
+ dest=f"{origin}:24001",
+ users=[credentials, download],
+ )
+ return dict(jls_download_credentials=download)
+
+
+if __name__ == "__main__":
+ import argparse
+
+ from .mihomo_isolation import exclusive_run
+ from .protocol_vless_container import CLIENT_FINGERPRINTS, run
+
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("output", type=Path)
+ parser.add_argument("cases", nargs="*")
+ parser.add_argument("--client-fingerprint", choices=CLIENT_FINGERPRINTS)
+ args = parser.parse_args()
+ with exclusive_run():
+ raise SystemExit(
+ run(
+ args.output.resolve(),
+ args.cases or None,
+ jls=True,
+ client_fingerprint=args.client_fingerprint,
+ )
+ )
diff --git a/scripts/src/vcore_scripts/protocol_peers.py b/scripts/src/vcore_scripts/protocol_peers.py
new file mode 100644
index 0000000..b385880
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_peers.py
@@ -0,0 +1,170 @@
+"""Owned native-peer processes. Stop is a wait barrier, never a global prune."""
+
+from __future__ import annotations
+
+import os
+import signal
+import socket
+import subprocess
+import tempfile
+import threading
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from .builds import CORE_DIR
+
+
+class OwnedProcess:
+ def __init__(
+ self,
+ command: list[str],
+ log: Path,
+ record: dict,
+ *,
+ env=None,
+ cwd=None,
+ limit=1024 * 1024,
+ ):
+ self.command, self.log_path, self.record = command, log, record
+ self.process = None
+ self.log = None
+ self.env, self.cwd, self.limit = env, cwd, limit
+ self.reader = None
+ self.overflow = threading.Event()
+
+ def __enter__(self):
+ self.record.update(started=False, joined=False)
+ self.log = self.log_path.open("wb")
+ try:
+ self.process = subprocess.Popen(
+ self.command,
+ stdout=subprocess.PIPE,
+ stderr=subprocess.STDOUT,
+ start_new_session=os.name != "nt",
+ stdin=subprocess.DEVNULL,
+ env=self.env,
+ cwd=self.cwd,
+ )
+ except BaseException:
+ self.log.close()
+ self.record["joined"] = True
+ raise
+ self.record["started"] = True
+ self.reader = threading.Thread(target=self._read, name="vcore-owned-output")
+ self.reader.start()
+ return self
+
+ def _read(self):
+ stored = 0
+ try:
+ while chunk := self.process.stdout.read(8192):
+ remaining = self.limit - stored
+ self.log.write(chunk[:remaining])
+ stored += min(len(chunk), remaining)
+ if len(chunk) > remaining:
+ self.overflow.set()
+ self._signal(signal.SIGKILL)
+ except OSError:
+ self.overflow.set()
+ finally:
+ self.process.stdout.close()
+
+ def _signal(self, value):
+ try:
+ if os.name == "nt":
+ if value == signal.SIGKILL:
+ self.process.kill()
+ else:
+ self.process.terminate()
+ else:
+ os.killpg(self.process.pid, value)
+ except ProcessLookupError:
+ pass
+
+ def _terminate(self):
+ if self.process.poll() is None:
+ self._signal(signal.SIGTERM)
+ try:
+ self.process.wait(timeout=5)
+ except subprocess.TimeoutExpired:
+ self._signal(signal.SIGKILL)
+ self.process.wait(timeout=5)
+
+ def _finish_reader(self):
+ if self.reader is not None:
+ self.reader.join(timeout=5)
+ if self.reader.is_alive():
+ self._signal(signal.SIGKILL)
+ self.reader.join(timeout=5)
+ if self.reader.is_alive():
+ raise RuntimeError("owned output reader did not stop")
+ if self.log is not None and not self.log.closed:
+ self.log.close()
+
+ def ensure_alive(self):
+ if self.overflow.is_set():
+ raise RuntimeError("native peer output exceeded its bound")
+ if self.process.poll() is not None:
+ self.record["unexpected_exit"] = self.process.returncode
+ raise RuntimeError("native peer exited before case completion")
+
+ def wait_tcp(self, port: int, seconds: float = 10, *, host: str = "127.0.0.1"):
+ deadline = time.monotonic() + seconds
+ while time.monotonic() < deadline:
+ self.ensure_alive()
+ try:
+ with socket.create_connection((host, port), 0.1):
+ self.record["ready"] = True
+ return
+ except OSError:
+ time.sleep(0.02)
+ raise TimeoutError("native peer readiness timeout")
+
+ def __exit__(self, *_):
+ try:
+ self._terminate()
+ self._finish_reader()
+ self.record.update(joined=True, exit_code=self.process.returncode)
+ finally:
+ if self.reader is None or not self.reader.is_alive():
+ self.log.close()
+
+
+@dataclass(frozen=True)
+class CommandResult:
+ returncode: int
+ stdout: bytes
+ cleanup: bool
+ seconds: float
+ reason: str | None
+
+
+def run_command(
+ command: list[str], *, timeout: float, env=None, cwd=None, limit=1024 * 1024
+) -> CommandResult:
+ """Bounded capture with process-group cleanup even on timeout or SIGINT."""
+ started = time.monotonic()
+ record = {}
+ reason = None
+ root = CORE_DIR / "target/interop/commands"
+ root.mkdir(parents=True, exist_ok=True)
+ with tempfile.TemporaryDirectory(prefix="command-", dir=root) as directory:
+ log = Path(directory) / "private.log"
+ with OwnedProcess(command, log, record, env=env, cwd=cwd, limit=limit) as owner:
+ try:
+ code = owner.process.wait(timeout=timeout)
+ except subprocess.TimeoutExpired:
+ code = 124
+ reason = "timeout"
+ if owner.overflow.is_set():
+ code = 125
+ reason = "output-limit"
+ output = log.read_bytes()
+ return CommandResult(
+ code,
+ output,
+ record.get("joined") is True,
+ round(time.monotonic() - started, 3),
+ reason,
+ )
diff --git a/scripts/src/vcore_scripts/protocol_preflight.py b/scripts/src/vcore_scripts/protocol_preflight.py
new file mode 100644
index 0000000..9d66692
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_preflight.py
@@ -0,0 +1,67 @@
+"""Independent native prerequisites. Artifact readiness is not wire acceptance."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .mihomo_release import download_mihomo, latest_release
+from .native_release import PeerArtifact, download_native
+from .protocol_catalogs import PEERS
+from .protocol_peers import run_command
+
+
+def preflight(directory: Path, kinds: set[str], *, container: bool = False):
+ if not kinds <= PEERS:
+ raise ValueError("unsupported native peer kind")
+ directory.mkdir(parents=True, exist_ok=True)
+ artifacts, records = {}, []
+ for kind in sorted(kinds):
+ record = {
+ "kind": kind,
+ "status": "BLOCKED",
+ "scope": "preflight-only",
+ "wire_acceptance": "NOT RUN",
+ }
+ records.append(record)
+ try:
+ if kind == "M":
+ identity = {}
+ release = latest_release()
+ binary = download_mihomo(
+ release=release, directory=directory / "M", identity=identity
+ )
+ version = run_command([str(binary), "-v"], timeout=10, limit=4096)
+ if version.returncode != 0 or not version.stdout.strip():
+ raise RuntimeError("official peer version query failed")
+ identity["version"] = version.stdout.decode(
+ "utf-8", errors="replace"
+ ).strip()
+ artifact = PeerArtifact(binary, identity)
+ artifacts[kind] = artifact
+ record.update(identity, status="READY")
+ if container:
+ record["container_status"] = "BLOCKED"
+ status = run_command(
+ ["container", "system", "status"], timeout=10, limit=4096
+ )
+ if status.returncode != 0:
+ raise RuntimeError("Apple Container is not running")
+ container_identity = {}
+ binary = download_mihomo(
+ "linux-arm64",
+ release=release,
+ directory=directory / "M-container",
+ identity=container_identity,
+ )
+ artifacts["M-container"] = PeerArtifact(binary, container_identity)
+ record.update(
+ container_status="READY", container_artifact=container_identity
+ )
+ else:
+ artifact = download_native(kind, directory / kind)
+ artifacts[kind] = artifact
+ record.update(artifact.identity, status="READY")
+ except (OSError, RuntimeError, ValueError) as error:
+ # Never expose URLs with userinfo, paths, config bodies or child output.
+ record["reason"] = type(error).__name__
+ return artifacts, records
diff --git a/scripts/src/vcore_scripts/protocol_reality_hybrid.py b/scripts/src/vcore_scripts/protocol_reality_hybrid.py
new file mode 100644
index 0000000..b4cacce
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_reality_hybrid.py
@@ -0,0 +1,536 @@
+"""Hybrid REALITY checks; not complete security suite acceptance."""
+
+from __future__ import annotations
+
+import contextlib
+import copy
+import hashlib
+import json
+import os
+import shutil
+import tempfile
+from pathlib import Path
+
+from .builds import CORE_DIR
+from .mihomo_isolation import exclusive_run
+from .mihomo_release import download_mihomo
+from .protocol_containers import ContainerLab, command
+from .protocol_evidence import read_events
+from .protocol_fixtures import certificates
+from .protocol_inputs import redact, same_source, source_identity
+from .protocol_peers import run_command
+from .protocol_vless_peers import configuration
+from .protocol_vless_public import events_pass
+
+MODES = {
+ "tcp": ("tcp-reality", None),
+ "ws": ("ws-reality", None),
+ "upgrade": ("upgrade-reality", None),
+ "upgrade-fast": ("upgrade-fast-reality", None),
+ "grpc": ("grpc-reality", None),
+ "vision": ("vision-reality", None),
+ **{
+ f"{version}-{mode}": (
+ f"xhttp-{mode}{'-download' if mode != 'stream-one' else ''}-reality",
+ alpn,
+ )
+ for version, alpn in (("h1", "http/1.1"), ("h2", "h2"))
+ for mode in ("stream-one", "stream-up", "packet-up")
+ },
+}
+
+
+def cases():
+ result = {}
+ for profile in ("none", "chrome"):
+ for mode in MODES:
+ result[f"{profile}-{mode}-base"] = (profile, mode, "public_base", "hybrid")
+ for variant in ("main-classic", "download-classic"):
+ for version in ("h1", "h2"):
+ result[f"{profile}-{version}-{variant}"] = (
+ profile,
+ f"{version}-stream-up",
+ "public_base",
+ variant,
+ )
+ for mode in ("tcp", "h1-stream-up", "h2-stream-up"):
+ result[f"{profile}-{mode}-security"] = (
+ profile,
+ mode,
+ "native_hybrid_fail_closed",
+ "hybrid",
+ )
+ result[f"{profile}-vision-inner-tls"] = (
+ profile,
+ "vision",
+ "native_vision_inner_tls",
+ "hybrid",
+ )
+ for test in (
+ "runtime::public_graph",
+ "runtime::public_ipv6_and_gates",
+ "runtime::public_entrypoints",
+ ):
+ result[f"{profile}-tcp-{test.split('::')[-1]}"] = (
+ profile,
+ "tcp",
+ test,
+ "hybrid",
+ )
+ for mode in ("tcp", "grpc", "vision", "h2-stream-up"):
+ for suffix, test in (
+ ("life", "runtime::public_lifecycle"),
+ ("owned", "runtime::owned_resources"),
+ ):
+ result[f"chrome-{mode}-{suffix}"] = ("chrome", mode, test, "hybrid")
+ return result
+
+
+def observed_events(observer):
+ raw = command(
+ "exec",
+ observer.name,
+ "python",
+ "-c",
+ "from pathlib import Path; p=Path('/data/events.jsonl'); "
+ "assert p.stat().st_size <= 8388608; print(p.read_text(),end='')",
+ )
+ return [json.loads(line) for line in raw.splitlines()]
+
+
+def wire_pass(events, expectations):
+ for port, (hybrid, profile) in expectations.items():
+ shares = (
+ [[4588, 1216], [29, 32]]
+ if hybrid and profile == "chrome"
+ else [[4588, 1216]]
+ if hybrid
+ else [[29, 32]]
+ )
+ hellos = [
+ e
+ for e in events
+ if e.get("port") == port and e.get("event") == "client-hello"
+ ]
+ selections = [
+ e
+ for e in events
+ if e.get("port") == port and e.get("event") == "server-hello"
+ ]
+ if (
+ not hellos
+ or not selections
+ or not all(e["shares"] == shares for e in hellos)
+ ):
+ return False
+ if not all(e["group"] == (4588 if hybrid else 29) for e in selections):
+ return False
+ return True
+
+
+def negative_wire_pass(events, profile, front=25000, legs=1):
+ for offset, cover, group in ((2, 24432, 29), (3, 24433, 24)):
+ observed = [e for e in events if e.get("port") == front + offset]
+ hellos = [e for e in observed if e.get("event") == "client-hello"]
+ replies = [e for e in observed if e.get("event") == "server-hello"]
+ if len(hellos) != legs:
+ return False
+ if profile == "chrome":
+ if (
+ len(replies) != legs
+ or not all(
+ e.get("group") == group and e.get("hrr") is (offset == 3)
+ for e in replies
+ )
+ or not all(
+ e.get("shares") == [[4588, 1216], [29, 32]]
+ and e.get("groups") == [4588, 29, 23, 24]
+ for e in hellos
+ )
+ ):
+ return False
+ else:
+ # A hybrid-only offer has no common group with these peers. A
+ # missing ServerHello alone is not proof: require the cover's
+ # native no-shared-group error and an empty, closed server flight.
+ rejected = [
+ e
+ for e in events
+ if e.get("port") == cover and e.get("event") == "no-shared-group"
+ ]
+ closed = [
+ e
+ for e in observed
+ if e.get("event") == "server-close" and e.get("bytes") == 0
+ ]
+ if (
+ replies
+ or len(rejected) != legs
+ or len(closed) != legs
+ or not all(
+ e.get("shares") == [[4588, 1216]] and e.get("groups") == [4588]
+ for e in hellos
+ )
+ ):
+ return False
+ return True
+
+
+def run(output: Path, selected=None, *, encryption=None, supplied=None):
+ output = output.resolve()
+ if not output.is_relative_to(CORE_DIR / "target/interop/runs"):
+ raise ValueError("use a fresh child of target/interop/runs")
+ required = cases()
+ selected = list(required) if selected is None else selected
+ if (
+ not selected
+ or len(set(selected)) != len(selected)
+ or not set(selected) <= required.keys()
+ ):
+ raise ValueError("invalid SECURITY.reality selection")
+ output.mkdir(parents=True, exist_ok=False)
+ report = dict(
+ stage="SECURITY.reality",
+ scope="S03/D16-production",
+ encryption_profile=encryption,
+ complete_selection=set(selected) == set(required),
+ required=list(required),
+ source=source_identity(),
+ cases=[],
+ isolation={},
+ peers={},
+ status="NOT RUN",
+ )
+ try:
+ if supplied is None:
+ identity = {}
+ binary = download_mihomo(
+ "linux-arm64", directory=output / "binaries", identity=identity
+ )
+ else:
+ binary, identity = supplied["M"]
+ report["peers"]["M"] = identity
+ built = run_command(
+ [
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ "vless_public",
+ "--test",
+ "vless_native",
+ "--no-run",
+ ],
+ timeout=240,
+ )
+ (output / "build.log").write_text(redact(built.stdout.decode(errors="replace")))
+ if built.returncode or not built.cleanup:
+ raise RuntimeError("SECURITY.reality consumer build failed")
+ lab = ContainerLab(report["isolation"], mtu=1500)
+ with (
+ tempfile.TemporaryDirectory(prefix="private-", dir=output) as temporary,
+ contextlib.ExitStack() as stack,
+ ):
+ root = Path(temporary)
+ origin_dir, server_dir, observer_dir, hop_dir = [
+ root / p for p in ("origin", "server", "observer", "hop")
+ ]
+ for directory in (origin_dir, server_dir, observer_dir, hop_dir):
+ directory.mkdir()
+ shutil.copy2(
+ Path(__file__).with_name("container_udp_origin.py"),
+ origin_dir / "origin.py",
+ )
+ shutil.copy2(
+ Path(__file__).with_name("container_reality_hybrid.py"),
+ observer_dir / "observer.py",
+ )
+ shutil.copy2(binary, server_dir / "peer")
+ shutil.copy2(binary, hop_dir / "peer")
+ cert, key, pin = certificates(origin_dir)
+ certificates(observer_dir)
+ origin = lab.start(
+ stack,
+ origin_dir,
+ "security-origin",
+ [
+ "env",
+ "VCORE_ISOLATED_ORIGIN=1",
+ f"VCORE_ORIGIN_CERT=/data/fixture/{cert.name}",
+ f"VCORE_ORIGIN_KEY=/data/fixture/{key.name}",
+ "python",
+ "-B",
+ "/data/fixture/origin.py",
+ ],
+ )
+ observer = lab.start(
+ stack,
+ observer_dir,
+ "security-observer",
+ [
+ "env",
+ "VCORE_ISOLATED_ORIGIN=1",
+ "python",
+ "-B",
+ "/data/fixture/observer.py",
+ ],
+ )
+ server = lab.start(
+ stack,
+ server_dir,
+ "security-mihomo",
+ [
+ "/data/fixture/peer",
+ "-d",
+ "/data/mihomo",
+ "-f",
+ "/data/fixture/config.json",
+ ],
+ )
+ hop = lab.start(
+ stack,
+ hop_dir,
+ "security-upstream",
+ [
+ "/data/fixture/peer",
+ "-d",
+ "/data/mihomo",
+ "-f",
+ "/data/fixture/config.json",
+ ],
+ )
+ listeners, routes, nodes, ports = [], {}, {}, {}
+ for index, (name, (mode, alpn)) in enumerate(MODES.items()):
+ node, config = configuration(
+ mode,
+ observer.ipv4,
+ origin.ipv4,
+ Path("/data/fixture/cert.pem"),
+ Path("/data/fixture/key.pem"),
+ )
+ backend, front = 23010 + index * 10, 25000 + index * 10
+ listener = config["listeners"][0]
+ if encryption:
+ from .protocol_encryption_public import configuration as encrypt
+
+ encrypt(encryption, node, config)
+ listener.update(name=name, port=backend)
+ listener["reality-config"]["dest"] = f"{observer.ipv4}:24431"
+ listeners.append(listener)
+ routes[str(front)] = routes[str(front + 1)] = [server.ipv4, backend]
+ if name == "tcp":
+ for offset, cover in ((2, 24432), (3, 24433)):
+ negative = copy.deepcopy(listener)
+ negative.update(name=f"reject-{cover}", port=backend + offset)
+ negative["reality-config"]["dest"] = f"{observer.ipv4}:{cover}"
+ listeners.append(negative)
+ routes[str(front + offset)] = [server.ipv4, backend + offset]
+ node.update(name="peer", port=front)
+ node["reality-opts"]["support-x25519mlkem768"] = True
+ if alpn:
+ node["alpn"] = [alpn]
+ if "download-settings" in node.get("xhttp-opts", {}):
+ node["xhttp-opts"]["download-settings"] = {
+ "server": observer.ipv4,
+ "port": front + 1,
+ }
+ nodes[name], ports[name] = node, front
+ (observer_dir / "routes.json").write_text(json.dumps(routes))
+ (server_dir / "config.json").write_text(
+ json.dumps(
+ {
+ "ipv6": True,
+ "log-level": "silent",
+ "listeners": listeners,
+ "hosts": {"vcore-fixture.test": origin.ipv4},
+ "rules": ["MATCH,DIRECT"],
+ }
+ )
+ )
+ (hop_dir / "config.json").write_text(
+ json.dumps(
+ {
+ "socks-port": 23001,
+ "allow-lan": True,
+ "bind-address": "*",
+ "log-level": "silent",
+ "ipv6": True,
+ "hosts": {"peer.fixture.test": observer.ipv4},
+ "rules": ["MATCH,DIRECT"],
+ }
+ )
+ )
+ for peer, port in (
+ (origin, 24000),
+ (observer, 24431),
+ (server, 23010),
+ (hop, 23001),
+ ):
+ peer.release()
+ peer.wait_tcp(port)
+ identity["version"] = command(
+ "exec", server.name, "/data/fixture/peer", "-v"
+ ).strip()
+ if (
+ command("exec", server.name, "sha256sum", "/data/fixture/peer").split()[
+ 0
+ ]
+ != identity["binary_sha256"]
+ ):
+ raise RuntimeError("native peer identity mismatch")
+ report["openssl"] = command(
+ "exec",
+ observer.name,
+ "python",
+ "-c",
+ "import ssl; print(ssl.OPENSSL_VERSION)",
+ ).strip()
+ for case in selected:
+ profile, mode, test, variant = required[case]
+ node = copy.deepcopy(nodes[mode])
+ node["client-fingerprint"] = profile
+ expectations = {ports[mode]: (True, profile)}
+ if node.get("xhttp-opts", {}).get("download-settings") is not None:
+ expectations[ports[mode] + 1] = (True, profile)
+ if variant != "hybrid":
+ down = node["xhttp-opts"]["download-settings"]
+ down["reality-opts"] = copy.deepcopy(node["reality-opts"])
+ if variant == "main-classic":
+ node["reality-opts"]["support-x25519mlkem768"] = False
+ expectations[ports[mode]] = (False, profile)
+ else:
+ down["reality-opts"]["support-x25519mlkem768"] = False
+ expectations[ports[mode] + 1] = (False, profile)
+ f = dict(
+ isolation="containers",
+ node=node,
+ origin_control=f"{origin.ipv4}:24000",
+ origin_ipv4=origin.ipv4,
+ origin_ipv6=origin.ipv6,
+ server_ipv6=observer.ipv6,
+ origin_pin=pin,
+ data_dir=str(root / "data"),
+ peer_kind="M",
+ vision_probe=mode == "vision",
+ hop=dict(
+ name="hop", type="socks5", server=hop.ipv4, port=23001, udp=True
+ ),
+ downgrade_port=ports["tcp"] + 2,
+ hrr_port=ports["tcp"] + 3,
+ ordinary_tls_port=24431,
+ tls12_port=24434,
+ )
+ fixture = root / "input.json"
+ fixture.write_text(json.dumps(f))
+ before = len(observed_events(observer))
+ events_path = output / f"{case}-events.jsonl"
+ test_command = [
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ "vless_native" if test.startswith("native_") else "vless_public",
+ test,
+ "--",
+ "--ignored",
+ "--exact",
+ "--nocapture",
+ ]
+ print(case, flush=True)
+ result = run_command(
+ test_command,
+ timeout=240,
+ env=dict(
+ os.environ,
+ VCORE_VLESS_INPUT=str(fixture),
+ VCORE_CASE_EVENTS=str(events_path),
+ VCORE_PROTOCOL_STAGE="SECURITY",
+ ),
+ )
+ (output / f"{case}.log").write_text(
+ redact(result.stdout.decode(errors="replace"))
+ )
+ observed = observed_events(observer)[before:]
+ wire_path = output / f"{case}-wire.json"
+ wire_path.write_text(json.dumps(observed, indent=2) + "\n")
+ events = read_events(events_path) if events_path.exists() else []
+ remapped = [
+ dict(e, suite=e.get("suite", "").replace("SECURITY-", "VLESS-", 1))
+ for e in events
+ ]
+ assertions = (
+ remapped
+ == [
+ dict(
+ schema_version=1,
+ suite="VLESS-WIRE",
+ assertion=test,
+ status=status,
+ )
+ for status in ("BEGIN", "PASS")
+ ]
+ if test.startswith("native_")
+ else events_pass(remapped, test, MODES[mode][0])
+ )
+ # Security matrices deliberately contain rejected peers; their
+ # strict per-attempt assertions require errors, never timeouts.
+ wire_valid = wire_pass(observed, expectations)
+ if test == "native_hybrid_fail_closed":
+ wire_valid &= negative_wire_pass(
+ observed, profile, ports["tcp"], len(expectations)
+ )
+ passed = (
+ result.returncode == 0
+ and result.cleanup
+ and assertions
+ and wire_valid
+ )
+ report["cases"].append(
+ dict(
+ id=case,
+ test=test,
+ variant=variant,
+ profile=profile,
+ status="PASS" if passed else "FAIL",
+ exit_code=result.returncode,
+ command_cleanup=result.cleanup,
+ seconds=result.seconds,
+ command=test_command,
+ wire_sha256=hashlib.sha256(wire_path.read_bytes()).hexdigest(),
+ assertions=assertions,
+ wire_valid=wire_valid,
+ )
+ )
+ print(f"{case}: {report['cases'][-1]['status']}", flush=True)
+ for peer in (origin, observer, server, hop):
+ peer.ensure_alive()
+ if not passed:
+ raise RuntimeError(f"SECURITY.reality case failed: {case}")
+ report["status"] = "PASS"
+ except KeyboardInterrupt:
+ report.update(status="INTERRUPTED", reason="user interruption")
+ except (OSError, RuntimeError, ValueError, KeyError) as error:
+ report.update(
+ status="FAIL",
+ reason=str(error)
+ if isinstance(error, RuntimeError)
+ else type(error).__name__,
+ )
+ finally:
+ report["cleanup"] = all(
+ p["joined"] for p in report["isolation"].get("peers", [])
+ )
+ report["source_unchanged"] = same_source(report["source"], source_identity())
+ if not report["cleanup"] or not report["source_unchanged"]:
+ report["status"] = "FAIL"
+ (output / "reality-results.json").write_text(
+ json.dumps(report, indent=2) + "\n"
+ )
+ return 0 if report["status"] == "PASS" else 1
+
+
+def main(output, selected=None):
+ with exclusive_run():
+ return run(output, selected)
diff --git a/scripts/src/vcore_scripts/protocol_script_tests.py b/scripts/src/vcore_scripts/protocol_script_tests.py
new file mode 100644
index 0000000..c0fa748
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_script_tests.py
@@ -0,0 +1,68 @@
+"""Structured unittest results for the protocol harness; no stdout PASS parsing."""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import sys
+import unittest
+from pathlib import Path
+
+from .builds import CORE_DIR
+
+
+class Result(unittest.TestResult):
+ def __init__(self):
+ super().__init__()
+ self.cases = []
+
+ def addSuccess(self, test):
+ super().addSuccess(test)
+ self.cases.append({"test": test.id(), "status": "PASS"})
+
+ def addFailure(self, test, error):
+ super().addFailure(test, error)
+ self.cases.append({"test": test.id(), "status": "FAIL", "reason": "assertion"})
+
+ def addError(self, test, error):
+ super().addError(test, error)
+ self.cases.append(
+ {"test": test.id(), "status": "FAIL", "reason": error[0].__name__}
+ )
+
+ def addSkip(self, test, reason):
+ super().addSkip(test, reason)
+ self.cases.append({"test": test.id(), "status": "NOT RUN"})
+
+
+class BoundedOutput(io.TextIOBase):
+ def __init__(self):
+ self.size = 0
+
+ def write(self, text):
+ self.size += len(text)
+ if self.size > 128 * 1024:
+ raise RuntimeError("script test output exceeded bound")
+ return len(text)
+
+
+def execute(path: Path) -> bool:
+ result = Result()
+ try:
+ suite = unittest.defaultTestLoader.discover(str(CORE_DIR / "scripts/tests"))
+ with (
+ contextlib.redirect_stdout(BoundedOutput()),
+ contextlib.redirect_stderr(BoundedOutput()),
+ ):
+ suite.run(result)
+ finally:
+ path.write_text(
+ json.dumps({"tests_run": result.testsRun, "cases": result.cases}, indent=2)
+ + "\n"
+ )
+ return result.testsRun > 0 and result.wasSuccessful() and not result.skipped
+
+
+if __name__ == "__main__":
+ raise SystemExit(0 if execute(Path(sys.argv[1])) else 1)
diff --git a/scripts/src/vcore_scripts/protocol_security_acceptance.py b/scripts/src/vcore_scripts/protocol_security_acceptance.py
new file mode 100644
index 0000000..5e264fc
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_security_acceptance.py
@@ -0,0 +1,662 @@
+"""Execute security cases and reconstruct results from commands and native events."""
+
+from __future__ import annotations
+
+import json
+import sys
+from contextlib import ExitStack
+
+from .protocol_evidence import HEX, new_result, read_events, read_json
+from .protocol_inputs import redact
+from .protocol_security_catalog import FIELDS, GATES, definitions, groups
+
+
+def commands(identifier):
+ from .protocol_hysteria2_acceptance import commands as previous
+
+ cargo = ["cargo", "test", "--locked", "--all-features"]
+ targets = [
+ "ech_config",
+ "ech_tls",
+ "encryption_config",
+ "reality_config",
+ "jls_config",
+ ]
+ if identifier in {"SECURITY-CFG", "SECURITY-RELEASE"}:
+ if identifier == "SECURITY-RELEASE":
+ cargo += ["--release"]
+ return [
+ cargo + sum((["--test", name] for name in targets), []),
+ cargo + ["--lib", "security::"],
+ cargo + ["--lib", "outbound::vless::encryption"],
+ cargo + ["--lib", "config::"],
+ ]
+ if identifier == "SECURITY-FEATURES":
+ return previous("HYSTERIA2-FEATURES") + [
+ [
+ "cargo",
+ "test",
+ "--locked",
+ "--no-default-features",
+ "--features",
+ "outbound-vless",
+ "--test",
+ "ech_config",
+ "--test",
+ "ech_tls",
+ ],
+ [
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--all-targets",
+ "--no-run",
+ ],
+ ]
+ if identifier == "SECURITY-SCRIPTS":
+ return [
+ [
+ sys.executable,
+ "-m",
+ "vcore_scripts.protocol_script_tests",
+ "{output}/script-tests.json",
+ ]
+ ]
+ return previous(identifier.replace("SECURITY-", "HYSTERIA2-"))
+
+
+def gate_result(case, records, events, script=None):
+ from .protocol_hysteria2_catalog import assertions_pass
+ from .protocol_security_units import TESTS
+
+ identifier = case["case_id"]
+ good = bool(records) and all(
+ r.get("exit_code") == 0 and r.get("cleanup") is True for r in records
+ )
+ if identifier in {"SECURITY-CFG", "SECURITY-RELEASE"}:
+ # Config and TLS tests each have an exact BEGIN/PASS pair. Library
+ # regressions run separately without these assertion identities.
+ selected = [e for e in events if e.get("suite") == "SECURITY-CONFIG-TLS"]
+ good &= assertions_pass(
+ selected,
+ {
+ ("SECURITY-CONFIG-TLS", name): 1
+ for names in TESTS.values()
+ for name in names
+ },
+ )
+ good &= all(e.get("status") in {"BEGIN", "PASS"} for e in events)
+ if identifier == "SECURITY-SCRIPTS":
+ samples = (script or {}).get("cases", [])
+ names = [s.get("test") for s in samples]
+ required = {
+ "test_protocol_security.SecurityAcceptanceTest." + name
+ for name in (
+ "test_frozen_scope_and_compositions",
+ "test_native_missing_duplicate_wrong_events_fail",
+ "test_source_cleanup_and_identity_are_not_inferred",
+ "test_empty_gate_and_missing_script_proof_fail",
+ "test_legacy_ech_gateway_keeps_response_inside_tls",
+ "test_close_reference_cannot_hide_a_different_official_profile",
+ )
+ }
+ required |= {
+ "test_protocol_containers.ContainerTests." + name
+ for name in (
+ "test_frozen_latest_image_is_single_run_owned",
+ "test_image_refresh_failure_never_falls_back_to_a_cached_image",
+ )
+ }
+ good &= (
+ bool(samples)
+ and len(names) == len(set(names)) == (script or {}).get("tests_run")
+ and required <= set(names)
+ and all(s.get("status") == "PASS" for s in samples)
+ )
+ return result(
+ case, good, bool(records) and all(r.get("cleanup") is True for r in records)
+ )
+
+
+def result(case, good, cleanup):
+ record = new_result(case)
+ record.update(
+ status="PASS" if good else "FAIL",
+ assertions={case["case_id"]: bool(good)},
+ evidence=case["required_evidence"] if good else [],
+ command_exit_code=0 if good else 1,
+ cleanup=cleanup,
+ )
+ return record
+
+
+def native_envelope(report, peers=None, source=None, *, image_digest=None):
+ isolation = report.get("isolation", {})
+ owned = isolation.get("peers", [])
+ identities = report.get("peers", {})
+ if "peer" in report:
+ identities = {"M": report["peer"]}
+ good = (
+ report.get("status") == "PASS"
+ and report.get("cleanup") is True
+ and report.get("source_unchanged") is True
+ and isolation.get("network_mode") == "hostOnly"
+ and isolation.get("host_servers") is False
+ and isolation.get("guest_mtu") == 1500
+ and isolation.get("image_digest", "").startswith("sha256:")
+ and bool(HEX.fullmatch(isolation.get("image_digest", "")[7:]))
+ and bool(owned)
+ and all(p.get("started") is True and p.get("joined") is True for p in owned)
+ and bool(identities)
+ )
+ for kind, identity in identities.items():
+ good &= (
+ bool(identity.get("version"))
+ and bool(HEX.fullmatch(identity.get("binary_sha256", "")))
+ and bool(HEX.fullmatch(identity.get("archive_sha256", "")))
+ and identity.get("source_url", "").startswith(
+ {
+ "M": "https://github.com/MetaCubeX/mihomo/releases/",
+ "XR": "https://github.com/XTLS/Xray-core/releases/",
+ "V2": "https://github.com/v2fly/v2ray-core/releases/",
+ }.get(kind, "invalid-source")
+ )
+ )
+ if peers is not None:
+ good &= identity == peers.get(kind)
+ if source is not None:
+ good &= report.get("source") == source
+ if image_digest is not None:
+ good &= isolation.get("image_digest") == image_digest
+ return bool(good)
+
+
+def rust_command(target, test, *, fields=False):
+ return [
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ target,
+ test,
+ "--",
+ *(["--exact", "--ignored"] if fields else ["--ignored", "--exact"]),
+ "--nocapture",
+ ]
+
+
+def vless_catalog(group):
+ if group.get("ech"):
+ from .protocol_ech import catalog
+
+ return catalog()
+ if group.get("jls"):
+ from .protocol_jls import catalog
+
+ return catalog()
+ from .protocol_vless_container import ALL_CASES
+
+ return ALL_CASES | {
+ "FINGERPRINT-ANYTLS": ("M", "anytls", True, "public_legacy_regression")
+ }
+
+
+def close_reference_pass(group, mode, directory):
+ profile = group.get("client_fingerprint")
+ expected_profile, scope = profile, "same-mode"
+ if mode == "grpc-tls":
+ if group.get("jls") and profile in (None, "", "none"):
+ expected_profile, scope = "chrome", "jls-grpc-chrome-baseline"
+ elif group.get("ech") and profile in ("safari", "safari16"):
+ expected_profile, scope = "chrome", "ech-safari-chrome-baseline"
+ try:
+ reference = read_json(directory / f"{mode}-tls-close-reference.json")
+ except (OSError, ValueError):
+ return False
+ return (
+ isinstance(reference, dict)
+ and reference.get("scope") == scope
+ and reference.get("client_fingerprint") == expected_profile
+ and reference.get("dut_client_fingerprint") == profile
+ and reference.get("terminated") is True
+ )
+
+
+def vless_pass(group, report, directory):
+ from .protocol_vless_public import events_pass
+
+ catalog = vless_catalog(group)
+ expected = group["selected"]
+ records = report.get("cases", [])
+ if len(records) != len(expected) or {r.get("case_id") for r in records} != set(
+ expected
+ ):
+ return False
+ if any(report.get(k) != group.get(k, False) for k in ("jls", "ech")):
+ return False
+ if report.get("encryption_profile") != group.get("encryption") or report.get(
+ "client_fingerprint"
+ ) != group.get("client_fingerprint"):
+ return False
+ stage = (
+ "SECURITY"
+ if group.get("ech") or group.get("jls") or group.get("encryption")
+ else "VLESS"
+ )
+ for record in records:
+ name = record["case_id"]
+ kind, mode, _, test = catalog[name]
+ native = test.startswith("native_")
+ events = read_events(directory / (name + "-events.jsonl"))
+ if not (
+ record.get("status") == "PASS"
+ and record.get("exit_code") == 0
+ and record.get("command_cleanup") is True
+ and record.get("cleanup") is True
+ and record.get("peer_kind") == kind
+ and record.get("command")
+ == rust_command("vless_native" if native else "vless_public", test)
+ ):
+ return False
+ if native:
+ if test == "native_mihomo_close_alignment" and not close_reference_pass(
+ group, mode, directory
+ ):
+ return False
+ if events != [
+ dict(
+ schema_version=1,
+ suite=stage + "-WIRE",
+ assertion=test,
+ status=status,
+ )
+ for status in ("BEGIN", "PASS")
+ ]:
+ return False
+ elif not events_pass(events, test, mode, stage=stage):
+ return False
+ return True
+
+
+def xhttp_pass(group, report, directory):
+ from .protocol_xhttp_fields import PUBLIC_TESTS, events_pass, public_events_pass
+
+ jobs = group["jobs"]
+ expected = {
+ entry["case_id"]: (variant, entry["test"])
+ for variant, entries in jobs.items()
+ for entry in entries
+ }
+ records = report.get("cases", [])
+ if len(records) != len(expected) or {r.get("case_id") for r in records} != set(
+ expected
+ ):
+ return False
+ if (
+ report.get("ech") != group.get("ech", False)
+ or report.get("jls") != group.get("jls", False)
+ or report.get("encryption_profile") != group.get("encryption")
+ ):
+ return False
+ for record in records:
+ variant, test = expected[record["case_id"]]
+ events = read_events(directory / (record["case_id"] + "-events.jsonl"))
+ if not (
+ record.get("variant") == variant
+ and record.get("assertion") == test
+ and record.get("status") == "PASS"
+ and record.get("exit_code") == 0
+ and record.get("command_cleanup") is True
+ and record.get("command")
+ == rust_command(
+ "vless_public" if test in PUBLIC_TESTS else "xhttp_native",
+ test,
+ fields=True,
+ )
+ ):
+ return False
+ if not (
+ public_events_pass(events, test)
+ if test in PUBLIC_TESTS
+ else events_pass(events, test, owned=test.startswith("lifecycle::"))
+ ):
+ return False
+ return True
+
+
+def hybrid_pass(group, report, directory):
+ from .protocol_reality_hybrid import MODES, cases, negative_wire_pass, wire_pass
+ from .protocol_vless_public import events_pass
+
+ catalog = cases()
+ records = report.get("cases", [])
+ selected = group["selected"]
+ if (
+ len(records) != len(selected)
+ or {r.get("id") for r in records} != set(selected)
+ or report.get("encryption_profile") != group.get("encryption")
+ ):
+ return False
+ ports = {mode: 25000 + i * 10 for i, mode in enumerate(MODES)}
+ for record in records:
+ name = record["id"]
+ profile, mode, test, variant = catalog[name]
+ expected = {ports[mode]: (True, profile)}
+ if mode.startswith(("h1-", "h2-")) and not mode.endswith("stream-one"):
+ expected[ports[mode] + 1] = (True, profile)
+ if variant != "hybrid":
+ expected[ports[mode] + (variant == "download-classic")] = (False, profile)
+ wire = read_json(directory / (name + "-wire.json"))
+ events = read_events(directory / (name + "-events.jsonl"))
+ native = test.startswith("native_")
+ good = (
+ record.get("status") == "PASS"
+ and record.get("exit_code") == 0
+ and record.get("command_cleanup") is True
+ and (record.get("test"), record.get("variant"), record.get("profile"))
+ == (test, variant, profile)
+ and record.get("command")
+ == rust_command("vless_native" if native else "vless_public", test)
+ and wire_pass(wire, expected)
+ )
+ if test == "native_hybrid_fail_closed":
+ good &= negative_wire_pass(wire, profile, ports["tcp"], len(expected))
+ good &= (
+ events
+ == [
+ dict(
+ schema_version=1,
+ suite="SECURITY-WIRE",
+ assertion=test,
+ status=status,
+ )
+ for status in ("BEGIN", "PASS")
+ ]
+ if native
+ else events_pass(events, test, MODES[mode][0], stage="SECURITY")
+ )
+ if not good:
+ return False
+ return True
+
+
+def encryption_pass(group, report, directory):
+ from .protocol_encryption import cases
+
+ expected = [
+ key
+ for key, (_, rtt, _) in cases().items()
+ if not group.get("expiry") or rtt == "0rtt"
+ ]
+ records = report.get("cases", [])
+ test = (
+ "native_ticket_expiry" if group.get("expiry") else "native_encryption_roundtrip"
+ )
+ marker = (
+ "SECURITY-ENCRYPTION-EXPIRY-PASS full-resumed-expired-full-resumed"
+ if group.get("expiry")
+ else "SECURITY-ENCRYPTION-WIRE-PASS rounds=4 bytes_per_direction=10485760"
+ )
+ if (
+ len(records) != len(expected)
+ or {r.get("case_id") for r in records} != set(expected)
+ or report.get("ticket_expiry") != group.get("expiry", False)
+ or report.get("cipher")
+ != ("chacha20-poly1305" if group.get("chacha") else "cpu-selected")
+ or report.get("padding") != "minimal"
+ ):
+ return False
+ for record in records:
+ log = (directory / (record["case_id"] + ".log")).read_text()
+ if not (
+ record.get("status") == "PASS"
+ and record.get("returncode") == 0
+ and record.get("cleanup") is True
+ and marker in log
+ and "1 passed; 0 failed; 0 ignored" in log
+ and record.get("command") == rust_command("encryption_wire", test)
+ ):
+ return False
+ return True
+
+
+REPORTS = {
+ "vless": "vless-results.json",
+ "xhttp": "xhttp-fields-results.json",
+ "hybrid": "reality-results.json",
+ "encryption": "encryption-results.json",
+}
+CHECKERS = {
+ "vless": vless_pass,
+ "xhttp": xhttp_pass,
+ "hybrid": hybrid_pass,
+ "encryption": encryption_pass,
+}
+
+
+def native_result(
+ case, group, report, directory, *, peers=None, source=None, image_digest=None
+):
+ good = native_envelope(report, peers, source, image_digest=image_digest)
+ good &= CHECKERS[group["runner"]](group, report, directory)
+ return result(case, good, report.get("cleanup") is True)
+
+
+def fields_report(cases, results):
+ by_id = {r["case_id"]: r for r in results}
+ rows = []
+ for field in sorted(FIELDS):
+ owners = [c["case_id"] for c in cases if field in c["row_ids"]]
+ cfg = [c for c in owners if c in {"SECURITY-CFG", "SECURITY-RELEASE"}]
+ wire = [c for c in owners if c not in GATES]
+ good = (
+ bool(cfg)
+ and bool(wire)
+ and all(by_id.get(c, {}).get("status") == "PASS" for c in owners)
+ )
+ rows.append(
+ dict(
+ id=field,
+ cfg_cases=cfg,
+ wire_cases=wire,
+ status="PASS" if good else "NOT RUN",
+ )
+ )
+ return dict(
+ stage="SECURITY", scope="selected-vless-security-consumers", fields=rows
+ )
+
+
+def execute(cases, run, output, results):
+ from .protocol_containers import frozen_image
+ from .protocol_encryption import run as run_encryption
+ from .protocol_harness import _command
+ from .protocol_reality_hybrid import run as run_hybrid
+ from .protocol_vless_container import run as run_vless
+ from .protocol_xhttp_acceptance import prepare_peers
+ from .protocol_xhttp_fields import run as run_xhttp
+
+ supplied = {}
+ image_scope = ExitStack()
+ catalog = groups()
+ source = {
+ k: run[k]
+ for k in (
+ "parent_commit",
+ "source_tree_sha256",
+ "dirty_patch_sha256",
+ "lock_sha256",
+ )
+ }
+ try:
+ for case in cases:
+ identifier = case["case_id"]
+ if identifier not in GATES:
+ continue
+ records, events = [], []
+ for i, argv in enumerate(commands(identifier)):
+ name = f"{identifier}-{i}"
+ path = output / (name + "-events.jsonl")
+ _command(
+ run,
+ output,
+ name,
+ [v.replace("{output}", str(output)) for v in argv],
+ case["timeout_seconds"],
+ events=path,
+ )
+ records.append(run["commands"][-1])
+ if path.exists():
+ events += read_events(path)
+ script = (
+ read_json(output / "script-tests.json")
+ if identifier == "SECURITY-SCRIPTS"
+ else None
+ )
+ results[identifier] = gate_result(case, records, events, script)
+ print(identifier + ": " + results[identifier]["status"], flush=True)
+ if results[identifier]["status"] != "PASS":
+ raise RuntimeError("SECURITY local gate failed: " + identifier)
+ if any(c["case_id"] in catalog for c in cases):
+ supplied = prepare_peers(output, {"M", "XR", "V2"})
+ run["container_image"] = image_scope.enter_context(
+ frozen_image(output / "container-image-pull.log")
+ )
+ runners = {
+ "vless": run_vless,
+ "xhttp": run_xhttp,
+ "hybrid": run_hybrid,
+ "encryption": run_encryption,
+ }
+ # Retained combinations first, followed by the longer new ECH matrix.
+ # Every required group still runs in this same frozen source/image scope.
+ for case in sorted(
+ cases,
+ key=lambda c: (c["case_id"].startswith("SECURITY-ECH-"), c["case_id"]),
+ ):
+ identifier = case["case_id"]
+ if identifier in GATES:
+ continue
+ group = catalog[identifier]
+ kwargs = {k: v for k, v in group.items() if k not in {"rows", "runner"}}
+ if group["runner"] == "xhttp":
+ kwargs["selected"] = list(kwargs["jobs"])
+ directory = output / identifier
+ runners[group["runner"]](directory, supplied=supplied, **kwargs)
+ report = read_json(directory / REPORTS[group["runner"]])
+ results[identifier] = native_result(
+ case,
+ group,
+ report,
+ directory,
+ peers={k: v[1] for k, v in supplied.items()},
+ source=source,
+ image_digest=run["container_image"]["digest"],
+ )
+ print(identifier + ": " + results[identifier]["status"], flush=True)
+ if results[identifier]["status"] != "PASS":
+ raise RuntimeError("SECURITY native gate failed: " + identifier)
+ finally:
+ image_scope.close()
+ (output / "peers.json").write_text(
+ json.dumps({k: v[1] for k, v in supplied.items()}, indent=2) + "\n"
+ )
+ (output / "fields.json").write_text(
+ json.dumps(fields_report(cases, list(results.values())), indent=2) + "\n"
+ )
+
+
+def check(run_dir, cases, run, results, peers, paths):
+ from .protocol_containers import IMAGE
+
+ snapshot = run.get("container_image", {})
+ digest = snapshot.get("digest", "")
+ if (
+ not isinstance(digest, str)
+ or not digest.startswith("sha256:")
+ or not HEX.fullmatch(digest[7:])
+ or snapshot
+ != dict(
+ tag=IMAGE,
+ digest=digest,
+ command=["container", "image", "pull", IMAGE],
+ exit_code=0,
+ cleanup=True,
+ log="container-image-pull.log",
+ )
+ or snapshot["log"] not in paths
+ ):
+ raise ValueError("missing or altered SECURITY frozen container image")
+ if (
+ cases != definitions()
+ or set(peers) != {"M", "XR", "V2"}
+ or not {"fields.json", "script-tests.json"} <= set(paths)
+ ):
+ raise ValueError("incomplete SECURITY stage artifacts or altered manifest")
+ records = run.get("commands", [])
+ names = {
+ f"{c['case_id']}-{i}"
+ for c in cases
+ for i, _ in enumerate(commands(c["case_id"]))
+ if c["case_id"] in GATES
+ }
+ if len(records) != len(names) or {r.get("name") for r in records} != names:
+ raise ValueError("missing, duplicate or extra SECURITY gate command")
+ actual = {r["case_id"]: r for r in results}
+ source = {
+ k: run[k]
+ for k in (
+ "parent_commit",
+ "source_tree_sha256",
+ "dirty_patch_sha256",
+ "lock_sha256",
+ )
+ }
+ catalog = groups()
+ for case in cases:
+ identifier = case["case_id"]
+ if identifier in GATES:
+ selected, events = [], []
+ for i, argv in enumerate(commands(identifier)):
+ record = next(r for r in records if r["name"] == f"{identifier}-{i}")
+ if (
+ record["command"]
+ != [redact(v.replace("{output}", str(run_dir))) for v in argv]
+ or record["log"] not in paths
+ ):
+ raise ValueError("SECURITY gate command or log changed")
+ selected.append(record)
+ path = run_dir / f"{identifier}-{i}-events.jsonl"
+ if path.exists():
+ events += read_events(path)
+ recalculated = gate_result(
+ case,
+ selected,
+ events,
+ read_json(run_dir / "script-tests.json")
+ if identifier == "SECURITY-SCRIPTS"
+ else None,
+ )
+ else:
+ group = catalog[identifier]
+ directory = run_dir / identifier
+ report = read_json(directory / REPORTS[group["runner"]])
+ recalculated = native_result(
+ case,
+ group,
+ report,
+ directory,
+ peers=peers,
+ source=source,
+ image_digest=digest,
+ )
+ if recalculated != actual[identifier] or recalculated["status"] != "PASS":
+ raise ValueError("SECURITY results differ from independent evidence")
+ fields = fields_report(cases, results)
+ if read_json(run_dir / "fields.json") != fields or any(
+ f["status"] != "PASS" for f in fields["fields"]
+ ):
+ raise ValueError("missing SECURITY field behavior coverage")
+ print(f"SECURITY: PASS ({len(cases)} required groups; {len(FIELDS)} field rows)")
diff --git a/scripts/src/vcore_scripts/protocol_security_catalog.py b/scripts/src/vcore_scripts/protocol_security_catalog.py
new file mode 100644
index 0000000..e2cbb9a
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_security_catalog.py
@@ -0,0 +1,331 @@
+"""Selected security requirements, independent of runtime results.
+
+This is an explicit covering set, not a Cartesian-product support claim. Encryption,
+hybrid REALITY and JLS have dedicated reports; this suite exercises their critical
+consumers together with static ECH and composition checks.
+"""
+
+from __future__ import annotations
+
+FIELDS = {"VL06", "S03", "S04", "S05", "S12", "S13", "D16", "D17", "D18", "D25", "D26"}
+ECH_FIELDS = ["S04", "S05", "D17", "D18"]
+JLS_FIELDS = ["S12", "S13", "D25", "D26"]
+HYBRID_FIELDS = ["S03", "D16"]
+GATES = {
+ "SECURITY-CFG",
+ "SECURITY-RELEASE",
+ "SECURITY-REGRESSION",
+ "SECURITY-QUALITY",
+ "SECURITY-FEATURES",
+ "SECURITY-SCRIPTS",
+ "SECURITY-PLATFORMS",
+}
+PROFILES = ("chrome", "chrome120", "firefox", "safari")
+ENCRYPTION = tuple(
+ f"{style}-{rtt}-mixed"
+ for style in ("native", "xorpub", "random")
+ for rtt in ("1rtt", "0rtt")
+)
+
+
+def groups():
+ from .protocol_ech import catalog as ech_catalog
+ from .protocol_jls import catalog as jls_catalog
+
+ result = {}
+
+ def add(name, runner, rows, **options):
+ result[name] = dict(runner=runner, rows=rows, **options)
+
+ add(
+ "SECURITY-ECH-STANDARD",
+ "vless",
+ ECH_FIELDS,
+ selected=list(ech_catalog()),
+ ech=True,
+ )
+ named = [
+ "SECURITY-ECH-TCP-TLS-BASE",
+ "SECURITY-ECH-TCP-TLS-REJECT",
+ "SECURITY-ECH-WS-TLS-BASE",
+ "SECURITY-ECH-GRPC-TLS-BASE",
+ "SECURITY-ECH-GRPC-TLS-CLOSE",
+ "SECURITY-ECH-TCP-MTLS-IDENTITY",
+ "SECURITY-ECH-XHTTP-STREAM-UP-DOWNLOAD-BASE",
+ "SECURITY-ECH-XHTTP-STREAM-UP-DOWNLOAD-REJECT",
+ "SECURITY-ECH-XHTTP-STREAM-UP-DOWNLOAD-DOWNLOAD",
+ "SECURITY-ECH-XHTTP-STREAM-UP-DOWNLOAD-H1-BASE",
+ "SECURITY-ECH-XHTTP-STREAM-UP-DOWNLOAD-H1-DOWNLOAD",
+ ]
+ for profile in PROFILES:
+ add(
+ "SECURITY-ECH-" + profile.upper(),
+ "vless",
+ ECH_FIELDS,
+ selected=named,
+ ech=True,
+ client_fingerprint=profile,
+ )
+
+ add(
+ "SECURITY-JLS-RETAINED",
+ "vless",
+ JLS_FIELDS,
+ jls=True,
+ selected=[
+ key
+ for key, (_, mode, _, test) in jls_catalog().items()
+ if mode
+ in {
+ "tcp-tls",
+ "grpc-tls",
+ "xhttp-stream-up-download",
+ "xhttp-stream-up-download-h1",
+ }
+ and test
+ in {
+ "public_base",
+ "native_jls_fail_closed",
+ "public_jls_download_identity",
+ "runtime::owned_resources",
+ "runtime::public_lifecycle",
+ "native_mihomo_close_alignment",
+ }
+ ],
+ )
+ add(
+ "SECURITY-HYBRID-RETAINED",
+ "hybrid",
+ HYBRID_FIELDS,
+ selected=[
+ f"{profile}-{mode}-{test}"
+ for profile in ("none", "chrome")
+ for mode in ("tcp", "h1-stream-up", "h2-stream-up")
+ for test in ("base", "security")
+ ]
+ + [
+ "chrome-vision-inner-tls",
+ "chrome-h2-stream-up-owned",
+ "chrome-h2-stream-up-life",
+ "chrome-h1-main-classic",
+ "chrome-h2-download-classic",
+ ],
+ )
+
+ for profile in ENCRYPTION:
+ suffix = profile.upper()
+ add(
+ "SECURITY-ECH-ENCRYPTION-" + suffix,
+ "vless",
+ ["VL06", *ECH_FIELDS],
+ ech=True,
+ encryption=profile,
+ client_fingerprint="chrome",
+ selected=[
+ "SECURITY-ECH-TCP-TLS-BASE",
+ "SECURITY-ECH-XHTTP-STREAM-UP-DOWNLOAD-BASE",
+ "SECURITY-ECH-XHTTP-STREAM-UP-DOWNLOAD-H1-BASE",
+ ],
+ )
+ add(
+ "SECURITY-JLS-ENCRYPTION-" + suffix,
+ "vless",
+ ["VL06", *JLS_FIELDS],
+ jls=True,
+ encryption=profile,
+ selected=[
+ "SECURITY-JLS-TCP-BASE",
+ "SECURITY-JLS-XHTTP-STREAM-UP-DOWNLOAD-BASE",
+ ],
+ )
+ add(
+ "SECURITY-HYBRID-ENCRYPTION-" + suffix,
+ "hybrid",
+ ["VL06", *HYBRID_FIELDS],
+ encryption=profile,
+ selected=[
+ "chrome-tcp-base",
+ "chrome-vision-base",
+ "chrome-h2-stream-up-base",
+ ],
+ )
+
+ def fields(name, rows, specs, **options):
+ jobs = {}
+ for variant, tests in specs:
+ jobs[variant] = [
+ dict(case_id=variant + "-" + str(i), test=test)
+ for i, test in enumerate(tests)
+ ]
+ add(name, "xhttp", rows, jobs=jobs, **options)
+
+ specs = [
+ (f"h3-{mode}-headers", ["public_base"])
+ for mode in ("stream-one", "stream-up", "packet-up")
+ ]
+ specs += [
+ (
+ f"h3-ech-{action}",
+ ["security::native_xhttp_security"]
+ if action.startswith("reject")
+ else ["public_base"],
+ )
+ for action in ("reject-main", "reject-download", "replace", "clear")
+ ]
+ specs += [
+ (
+ "h3-stream-up-reuse",
+ [
+ "runtime::public_graph",
+ "runtime::public_entrypoints",
+ "runtime::public_ipv6_and_gates",
+ "runtime::public_udp_isolation",
+ "runtime::public_lifecycle",
+ "lifecycle::native_xhttp_owned_resources",
+ ],
+ ),
+ ("h3-keepalive", ["keepalive::native_h3_keepalive_observes_each_leg_and_stop"]),
+ ]
+ fields("SECURITY-ECH-H3", ECH_FIELDS, specs, ech=True)
+ for security in ("ech", "jls"):
+ versions = ("h1", "h2", "h3") if security == "ech" else ("h1", "h2")
+ specs = [
+ (f"{version}-mux-{mux}-padded{only}", ["public_base"])
+ for version in versions
+ for mux in ("h2mux", "smux", "yamux")
+ for only in ("", "-only-tcp")
+ ]
+ fields(
+ "SECURITY-" + security.upper() + "-MUX",
+ ECH_FIELDS if security == "ech" else JLS_FIELDS,
+ specs,
+ **{security: True},
+ encryption="native-0rtt-mixed",
+ )
+ fields(
+ "SECURITY-ECH-NATIVE-TRANSPORT",
+ ECH_FIELDS,
+ [
+ ("outer-" + transport + "-tls", ["public_base"])
+ for transport in ("http", "h2", "ws-header", "ws-path")
+ ],
+ ech=True,
+ encryption="native-0rtt-mixed",
+ )
+
+ fields(
+ "SECURITY-ECH-H3-ENCRYPTION",
+ ["VL06", *ECH_FIELDS],
+ [
+ (f"h3-{mode}-headers", ["public_base"])
+ for mode in ("stream-one", "stream-up", "packet-up")
+ ]
+ + [("h3-ech-replace", ["public_base"])],
+ ech=True,
+ encryption="native-0rtt-mixed",
+ )
+
+ add("SECURITY-ENCRYPTION-WIRE", "encryption", ["VL06"])
+ add("SECURITY-ENCRYPTION-CHACHA", "encryption", ["VL06"], chacha=True)
+ add("SECURITY-ENCRYPTION-EXPIRY", "encryption", ["VL06"], expiry=True)
+ for profile in ("none", "chrome"):
+ add(
+ "SECURITY-SHARED-" + profile.upper(),
+ "vless",
+ [],
+ client_fingerprint=profile,
+ selected=[
+ "VLESS-TCP-TLS-BASE",
+ "VLESS-TCP-TLS-NEG",
+ "VLESS-TCP-REALITY-BASE",
+ "VLESS-TCP-REALITY-NEG",
+ "VLESS-VISION-REALITY-BASE",
+ "VLESS-GRPC-TLS-BASE",
+ "VLESS-HTTP-TLS-BASE",
+ "VLESS-H2-TLS-BASE",
+ "VLESS-REGRESSION-TROJAN-TCP",
+ "VLESS-REGRESSION-VMESS-GRPC",
+ "FINGERPRINT-ANYTLS",
+ ],
+ )
+ fields(
+ "SECURITY-SHARED-XHTTP",
+ [],
+ [
+ ("h1-stream-up-split-reuse", ["public_base"]),
+ ("h2-stream-up-split-reuse", ["public_base"]),
+ ("h3-stream-up-split-reuse", ["public_base"]),
+ ("h2r-stream-up-split-reuse", ["public_base"]),
+ ("h3-mux-yamux-padded", ["public_base"]),
+ ],
+ )
+ return result
+
+
+def definitions():
+ native = groups()
+ result = []
+ for identifier in sorted(GATES | native.keys()):
+ group = native.get(identifier, {})
+ runner = group.get("runner", "gate")
+ rows = sorted(
+ FIELDS
+ if identifier in {"SECURITY-CFG", "SECURITY-RELEASE"}
+ else group.get("rows", [])
+ )
+ options = {k: v for k, v in group.items() if k not in {"rows", "runner"}}
+ kind = (
+ "unit"
+ if not group
+ else (
+ "XR" if "H3" in identifier or "NATIVE-TRANSPORT" in identifier else "M"
+ )
+ )
+ result.append(
+ dict(
+ case_id=identifier,
+ stage="SECURITY",
+ substage="SECURITY.acceptance",
+ required=True,
+ row_ids=rows,
+ protocol="vless",
+ network="explicit-selected-compositions",
+ security="static-ech/encryption/hybrid-reality/jls",
+ udp_codec="raw/xudp/packetaddr/sing-mux",
+ field_values=options,
+ outer_family="IPv4/IPv6",
+ inner_family="IPv4/IPv6/domain",
+ target_type=(
+ "memory-only/build"
+ if kind == "unit"
+ else "isolated synthetic origin"
+ ),
+ upstream_graph="direct/concrete/nested-select",
+ peer_kind=kind,
+ peer_config=dict(runner=runner, **options),
+ gap_source=dict(
+ reason="Mihomo v1.19.31 Safari ECH fails before business data. "
+ "Only the gRPC close reference uses Chrome with the same ECH "
+ "listener; VCore remains Safari, not a same-profile comparison.",
+ source="https://github.com/MetaCubeX/utls/blob/v1.8.7/u_handshake_client.go",
+ )
+ if identifier == "SECURITY-ECH-SAFARI"
+ else None
+ if kind != "XR"
+ else dict(
+ reason="Mihomo has no H3 or legacy HTTP/H2/extended WS listener; "
+ "official Xray/V2Ray terminate that transport, with "
+ "Mihomo VLESS for packetaddr, Encryption and sing-mux.",
+ source="https://github.com/XTLS/Xray-core",
+ ),
+ expected_observation=[identifier],
+ required_evidence=["command", "cleanup", "structured-assertions"]
+ + ([] if kind == "unit" else ["peer-identity", "isolated-origins"]),
+ prerequisites=["rust-toolchain"]
+ if kind == "unit"
+ else ["owned-host-only-container-network", "official-latest-peer"],
+ runner="vless-security-" + runner,
+ timeout_seconds=3600,
+ )
+ )
+ return result
diff --git a/scripts/src/vcore_scripts/protocol_security_units.py b/scripts/src/vcore_scripts/protocol_security_units.py
new file mode 100644
index 0000000..b49398c
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_security_units.py
@@ -0,0 +1,42 @@
+# Exact configuration and in-memory TLS assertion identities for SECURITY.
+TESTS = {
+ "ech_config": [
+ "static_ech_builds_both_tls_backends_without_dns_or_io",
+ "static_ech_is_strict_and_never_enables_dynamic_lookup",
+ "unsupported_ech_configs_fail_at_parse_before_a_client_can_emit_inner_sni",
+ "ech_selection_skips_unknown_or_mandatory_configs_and_keeps_exact_supported_bytes",
+ "download_ech_inherits_replaces_or_clears_as_a_whole",
+ "ech_is_standard_tls_only_with_explicit_download_clear_and_dns_inner_name",
+ ],
+ "ech_tls": [
+ "rejected_or_wrong_key_ech_never_reaches_application_data_even_with_a_matching_pin",
+ "client_identity_is_sent_only_after_ech_acceptance",
+ "cancelled_ech_emits_only_public_sni_and_releases_io_for_every_backend",
+ "each_backend_and_hpke_suite_requires_real_ech_acceptance_before_data",
+ ],
+ "encryption_config": [
+ "public_encryption_accepts_all_six_modes_without_exposing_key_material",
+ "vision_encryption_is_independent_of_outer_tls_but_keeps_transport_and_udp_limits",
+ ],
+ "reality_config": [
+ "public_reality_accepts_explicit_hybrid_without_replacing_the_fingerprint",
+ "public_reality_rejects_profiles_without_the_required_hybrid_share",
+ "download_inherits_or_replaces_the_entire_reality_object_without_leaf_merging",
+ "hybrid_flag_is_a_strict_nonnullable_boolean_on_both_legs",
+ "classic_default_and_explicit_false_preserve_all_existing_profiles",
+ "inherited_profile_is_validated_after_download_reality_replacement",
+ "hybrid_reality_cannot_be_combined_with_h3_or_plaintext_on_either_leg",
+ ],
+ "jls_config": [
+ "public_jls_builds_an_authenticated_security_client_without_exposing_credentials",
+ "independent_download_inherits_jls_identity_and_applies_its_own_tls_fields",
+ "download_jls_credentials_are_replaced_as_a_whole_or_explicitly_cleared",
+ "malformed_or_partial_credentials_never_inherit_a_missing_secret",
+ "invalid_jls_objects_do_not_echo_credentials_in_public_configuration_errors",
+ "jls_rejects_incompatible_security_at_configuration_time",
+ "download_security_switch_requires_explicit_clearing_of_inherited_identity",
+ "selected_profiles_build_jls_without_changing_its_identity",
+ "cancelled_jls_handshakes_release_supplied_io_and_never_reuse_randoms",
+ "jls_security_client_rejects_ordinary_tls_before_application_data",
+ ],
+}
diff --git a/scripts/src/vcore_scripts/protocol_streams.py b/scripts/src/vcore_scripts/protocol_streams.py
new file mode 100644
index 0000000..30e6202
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_streams.py
@@ -0,0 +1,310 @@
+"""Transport-only native cases; synthetic VLESS is not public YAML support."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import socket
+import socketserver
+import subprocess
+import tempfile
+import threading
+import time
+from pathlib import Path
+
+from .builds import CORE_DIR
+from .mihomo_isolation import reserve_port
+from .protocol_fixtures import certificates
+from .protocol_peers import OwnedProcess, run_command
+from .protocol_preflight import preflight
+
+CLIENT_ID = "b831381d-6324-4d53-ad4f-8cda48b30811" # Public synthetic identity.
+GREETING, TRAILER = b"FOUNDATIONS-server-first\n", b"FOUNDATIONS-half-close\n"
+STREAM_CASES = {
+ "FOUNDATIONS-M-WS": ("M", "ws"),
+ "FOUNDATIONS-M-WSS": ("M", "wss"),
+ "FOUNDATIONS-M-GRPC": ("M", "grpc"),
+ "FOUNDATIONS-M-GRPC-TLS": ("M", "grpc-tls"),
+ "FOUNDATIONS-M-WS-ED": ("M", "ws-header"),
+ "FOUNDATIONS-V2-HTTP": ("V2", "http"),
+ "FOUNDATIONS-V2-H2": ("V2", "h2"),
+ "FOUNDATIONS-V2-WS-HEADER": ("V2", "ws-header"),
+ "FOUNDATIONS-V2-WS-PATH": ("V2", "ws-path"),
+}
+
+
+def abnormal_cleanup(binary: Path, directory: Path, cert: Path, key: Path) -> dict:
+ """A real native peer must be joined even when its calling case unwinds."""
+
+ class InjectedFailure(Exception):
+ pass
+
+ record = {}
+ with contextlib.ExitStack() as stack:
+ port, reservation = reserve_port(stack)
+ config = directory / "cleanup-peer.json"
+ config.write_text(json.dumps(peer_config("M", "ws", port, cert, key)))
+ reservation.release_ipv4()
+ owner = OwnedProcess(
+ [str(binary), "-d", str(directory), "-f", str(config)],
+ directory / "cleanup-peer.log",
+ record,
+ )
+ try:
+ with owner:
+ owner.wait_tcp(port)
+ raise InjectedFailure
+ except InjectedFailure:
+ pass
+ with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as rebind:
+ rebind.bind(("127.0.0.1", port))
+ if not record.get("joined") or owner.process.poll() is None:
+ raise RuntimeError("native abnormal cleanup failed")
+ return {
+ "passed": True,
+ "kind": "M",
+ "failure_injected": True,
+ "joined": True,
+ "port_rebound": True,
+ }
+
+
+class Echo(socketserver.BaseRequestHandler):
+ def handle(self):
+ self.server.accepted += 1
+ self.request.settimeout(15)
+ try:
+ self.request.sendall(GREETING)
+ while data := self.request.recv(8192):
+ self.server.received += len(data)
+ self.request.sendall(data)
+ if self.server.received >= 65536:
+ break
+ self.request.sendall(TRAILER)
+ except OSError:
+ self.server.failed = True
+ finally:
+ self.server.finished.set()
+
+
+@contextlib.contextmanager
+def origin():
+ with socketserver.TCPServer(("127.0.0.1", 0), Echo) as server:
+ server.accepted, server.received, server.failed = 0, 0, False
+ server.finished = threading.Event()
+ thread = threading.Thread(target=server.serve_forever)
+ thread.start()
+ try:
+ yield server
+ finally:
+ server.shutdown()
+ thread.join(timeout=20)
+ if thread.is_alive():
+ raise RuntimeError("origin cleanup failed")
+
+
+def peer_config(kind, mode, port, cert, key):
+ encrypted = mode in {"wss", "grpc-tls", "h2"}
+ if kind == "M":
+ listener = {
+ "name": "foundations-stream",
+ "type": "vless",
+ "listen": "127.0.0.1",
+ "port": port,
+ "users": [{"uuid": CLIENT_ID}],
+ }
+ if encrypted:
+ listener.update(certificate=str(cert), **{"private-key": str(key)})
+ else:
+ listener["allow-insecure"] = True # Explicit loopback-only plaintext.
+ if mode.startswith("ws"):
+ listener["ws-path"] = "/foundations-ws"
+ if mode.startswith("grpc"):
+ listener["grpc-service-name"] = "foundations-grpc"
+ return {
+ "mode": "rule",
+ "log-level": "silent",
+ "allow-lan": False,
+ "bind-address": "127.0.0.1",
+ "listeners": [listener],
+ "rules": ["MATCH,DIRECT"],
+ }
+ stream = {"network": "tcp", "security": "tls" if encrypted else "none"}
+ if mode == "http":
+ stream["tcpSettings"] = {
+ "header": {"type": "http", "request": {"path": ["/foundations-http"]}}
+ }
+ elif mode == "h2":
+ stream.update(
+ network="http",
+ httpSettings={"host": ["localhost"], "path": "/foundations-h2"},
+ )
+ else:
+ stream.update(
+ network="ws",
+ wsSettings={
+ "path": "/foundations-ws",
+ "maxEarlyData": 2048,
+ "earlyDataHeaderName": "x-vcore-ed" if mode == "ws-header" else "",
+ },
+ )
+ if encrypted:
+ stream["tlsSettings"] = {
+ "alpn": ["h2"],
+ "certificates": [{"certificateFile": str(cert), "keyFile": str(key)}],
+ }
+ return {
+ "log": {"loglevel": "none"},
+ "inbounds": [
+ {
+ "listen": "127.0.0.1",
+ "port": port,
+ "protocol": "vless",
+ "settings": {"clients": [{"id": CLIENT_ID}], "decryption": "none"},
+ "streamSettings": stream,
+ }
+ ],
+ "outbounds": [{"protocol": "freedom", "settings": {}}],
+ }
+
+
+def run_streams(output: Path, selected: list[str] | None = None, *, artifacts=None):
+ selected = list(STREAM_CASES) if selected is None else selected
+ if (
+ not selected
+ or len(set(selected)) != len(selected)
+ or not set(selected) <= STREAM_CASES.keys()
+ ):
+ raise RuntimeError("invalid native stream case selection")
+ output.mkdir(parents=True, exist_ok=False)
+ report = {
+ "scope": "FOUNDATIONS-shared-transport-only",
+ "cases": [],
+ "peers": [],
+ "cleanup": False,
+ }
+ try:
+ kinds = {STREAM_CASES[case][0] for case in selected}
+ if artifacts is None:
+ artifacts, report["preflight"] = preflight(output / "binaries", kinds)
+ peers = {kind: item.binary for kind, item in artifacts.items() if kind in kinds}
+ report["peers"] = [
+ item.identity for kind, item in artifacts.items() if kind in kinds
+ ]
+ with tempfile.TemporaryDirectory(prefix="private-", dir=output) as temporary:
+ temporary = Path(temporary)
+ cert, key, pin = certificates(temporary)
+ if "M" in peers:
+ report["abnormal_cleanup"] = abnormal_cleanup(
+ peers["M"], temporary, cert, key
+ )
+ for case_id in selected:
+ kind, mode = STREAM_CASES[case_id]
+ record = {
+ "case_id": case_id,
+ "peer_kind": kind,
+ "mode": mode,
+ "status": "NOT RUN",
+ "cleanup": {},
+ }
+ report["cases"].append(record)
+ if kind not in peers:
+ record.update(
+ status="BLOCKED",
+ reason="required peer unavailable",
+ cleanup={"joined": True, "started": False},
+ )
+ continue
+ started = time.monotonic()
+ try:
+ with contextlib.ExitStack() as stack:
+ port, reservation = reserve_port(stack)
+ config = temporary / "peer.json"
+ config.write_text(
+ json.dumps(peer_config(kind, mode, port, cert, key))
+ )
+ command = (
+ [str(peers[kind]), "-d", str(temporary), "-f", str(config)]
+ if kind == "M"
+ else [str(peers[kind]), "run", "-c", str(config)]
+ )
+ reservation.release_ipv4()
+ peer = stack.enter_context(
+ OwnedProcess(
+ command, temporary / "peer.log", record["cleanup"]
+ )
+ )
+ peer.wait_tcp(port)
+ with origin() as echo:
+ fixture = {
+ "mode": mode,
+ "server": f"127.0.0.1:{port}",
+ "target": f"127.0.0.1:{echo.server_address[1]}",
+ "pin": pin,
+ "ed_header": "sec-websocket-protocol"
+ if kind == "M"
+ else "x-vcore-ed",
+ }
+ probe_config = temporary / "probe.json"
+ probe_config.write_text(json.dumps(fixture))
+ completed = run_command(
+ [
+ str(
+ CORE_DIR
+ / "target/debug/examples/protocol-stream-probe"
+ ),
+ str(probe_config),
+ ],
+ timeout=20,
+ limit=65536,
+ )
+ result = json.loads(completed.stdout)
+ record["rust_event"] = result
+ record["command_exit_code"] = completed.returncode
+ record["origin"] = {
+ "finished": echo.finished.wait(3),
+ "accepted": echo.accepted,
+ "received": echo.received,
+ "failed": echo.failed,
+ }
+ peer.ensure_alive()
+ record["status"] = (
+ "PASS"
+ if completed.returncode == 0
+ and result["outcome"] == "pass"
+ and result["driver_joined"]
+ and result["protect_calls"] == 1
+ and result.get("resources_idle") is True
+ and result.get("server_first") is True
+ and result.get("payload_bytes") == 65536
+ and result.get("tail_bytes") == len(TRAILER)
+ and completed.cleanup
+ and record["origin"]
+ == {
+ "finished": True,
+ "accepted": 1,
+ "received": 65536,
+ "failed": False,
+ }
+ else "FAIL"
+ )
+ except (
+ OSError,
+ ValueError,
+ RuntimeError,
+ subprocess.SubprocessError,
+ ) as error:
+ record.update(status="FAIL", reason=type(error).__name__)
+ finally:
+ record["seconds"] = round(time.monotonic() - started, 3)
+ if not record["cleanup"].get("joined"):
+ record["status"] = "FAIL"
+ print(json.dumps(record), flush=True)
+ report["cleanup"] = True
+ finally:
+ (output / "stream-cases.json").write_text(json.dumps(report, indent=2) + "\n")
+ if not report["cleanup"] or any(
+ case["status"] != "PASS" for case in report["cases"]
+ ):
+ raise RuntimeError("native stream cases did not pass; see structured report")
+ return report
diff --git a/scripts/src/vcore_scripts/protocol_trojan.py b/scripts/src/vcore_scripts/protocol_trojan.py
new file mode 100644
index 0000000..f44ae82
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_trojan.py
@@ -0,0 +1,363 @@
+"""TROJAN public Trojan consumer acceptance against owned official native peers."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import tempfile
+from pathlib import Path
+
+from .builds import CORE_DIR
+from .mihomo_isolation import reserve_port
+from .protocol_evidence import idle_resources, read_events
+from .protocol_fixtures import certificate_chain, certificates
+from .protocol_fixtures import trojan_peer_config as peer_config
+from .protocol_inputs import redact, source_identity
+from .protocol_peers import OwnedProcess, run_command
+from .protocol_preflight import preflight
+
+CASES = {
+ "TROJAN-M-TCP": ("M", "tcp", "public_trojan_native_base"),
+ "TROJAN-M-WS": ("M", "ws", "public_trojan_native_base"),
+ "TROJAN-M-GRPC": ("M", "grpc", "public_trojan_native_base"),
+ "TROJAN-M-WS-ED-1": ("M", "ws-ed-1", "public_trojan_native_base"),
+ "TROJAN-M-WS-ED-2048": ("M", "ws-ed-2048", "public_trojan_native_base"),
+ "TROJAN-M-WS-POLICY": (
+ "M",
+ "ws",
+ "public_trojan_native_policy_and_group_snapshots",
+ ),
+ "TROJAN-M-GRPC-POLICY": (
+ "M",
+ "grpc",
+ "public_trojan_native_policy_and_group_snapshots",
+ ),
+ "TROJAN-M-WS-NEGATIVE": ("M", "ws", "public_trojan_native_transport_negative"),
+ "TROJAN-M-GRPC-NEGATIVE": ("M", "grpc", "public_trojan_native_transport_negative"),
+ "TROJAN-M-ALPN-NEGATIVE": (
+ "M",
+ "ws-alpn",
+ "public_trojan_native_transport_negative",
+ ),
+ "TROJAN-V2-WS-HEADER": (
+ "V2",
+ "ws-header",
+ "public_trojan_native_extended_early_data",
+ ),
+ "TROJAN-V2-WS-PATH": ("V2", "ws-path", "public_trojan_native_extended_early_data"),
+ "TROJAN-M-TCP-POLICY": (
+ "M",
+ "tcp",
+ "public_trojan_native_policy_and_group_snapshots",
+ ),
+ "TROJAN-XR-UDP-DOMAIN": ("XR", "tcp", "public_trojan_native_udp_domain"),
+ "TROJAN-XR-WS-UDP-DOMAIN": ("XR", "ws", "public_trojan_native_udp_domain"),
+ "TROJAN-XR-GRPC-UDP-DOMAIN": ("XR", "grpc", "public_trojan_native_udp_domain"),
+}
+for _mode in ("tcp", "ws", "grpc"):
+ for _suffix, _test in (
+ ("LIFE", "runtime::public_trojan_native_lifecycle"),
+ ("ENTRYPOINTS", "runtime::public_trojan_native_entrypoints"),
+ ("UDP-ISOLATION", "runtime::public_trojan_native_udp_isolation_and_limit"),
+ ):
+ CASES[f"TROJAN-M-{_mode.upper()}-{_suffix}"] = ("M", _mode, _test)
+ CASES[f"TROJAN-M-{_mode.upper()}-IPV6"] = (
+ "M",
+ _mode + "-ipv6",
+ "public_trojan_native_base",
+ )
+ CASES[f"TROJAN-M-{_mode.upper()}-OWNED"] = (
+ "M",
+ _mode,
+ "trojan_native_owned_resources",
+ )
+ CASES[f"TROJAN-M-{_mode.upper()}-CERTIFICATE"] = (
+ "M",
+ _mode + "-ca",
+ "runtime::public_trojan_native_certificate_names",
+ )
+CASES["TROJAN-M-GRPC-CUSTOM"] = ("M", "grpc-custom", "public_trojan_native_base")
+
+
+def native_events_pass(events, test):
+ suites = {"TROJAN-NATIVE"}
+ if test == "runtime::public_trojan_native_lifecycle":
+ suites.add("TROJAN-LIFE-CYCLE")
+ elif test == "trojan_native_owned_resources":
+ suites.add("TROJAN-OWNED-CYCLE")
+ main = [event for event in events if event.get("suite") == "TROJAN-NATIVE"]
+ if (
+ len(main) != 2
+ or any(
+ event.get("assertion") != test or event.get("schema_version") != 1
+ for event in main
+ )
+ or [event.get("status") for event in main] != ["BEGIN", "PASS"]
+ ):
+ return False
+ if test in {
+ "runtime::public_trojan_native_lifecycle",
+ "trojan_native_owned_resources",
+ }:
+ suite = (
+ "TROJAN-OWNED-CYCLE"
+ if test == "trojan_native_owned_resources"
+ else "TROJAN-LIFE-CYCLE"
+ )
+ cycles = [event for event in events if event.get("suite") == suite]
+ if len(cycles) != 40:
+ return False
+ for begin, end in zip(cycles[::2], cycles[1::2], strict=True):
+ if (
+ begin.get("status") != "BEGIN"
+ or end.get("status") != "PASS"
+ or end.get("seconds", 0) < 5
+ or any(
+ event.get("assertion") != "stop_and_remain_quiet"
+ or event.get("schema_version") != 1
+ for event in (begin, end)
+ )
+ ):
+ return False
+ if suite == "TROJAN-OWNED-CYCLE":
+ points = end.get("checkpoints", [])
+ phases = {point["phase"]: point["resources"] for point in points}
+ if (
+ len(points) != 3
+ or set(phases) != {"baseline", "after-stop", "quiet"}
+ or not all(idle_resources(value) for value in phases.values())
+ or phases["after-stop"] != phases["quiet"]
+ or not idle_resources(end.get("resources"))
+ ):
+ return False
+ return all(
+ event.get("status") in {"BEGIN", "PASS"}
+ and event.get("schema_version") == 1
+ and event.get("suite") in suites
+ for event in events
+ )
+
+
+def run(output: Path, selected=None, *, artifacts=None):
+ selected = list(CASES) if selected is None else selected
+ if (
+ not selected
+ or len(selected) != len(set(selected))
+ or not set(selected) <= CASES.keys()
+ ):
+ raise ValueError("invalid TROJAN case selection")
+ output.mkdir(parents=True, exist_ok=False)
+ report = {
+ "stage": "TROJAN",
+ "scope": "protocol-consumer",
+ "source": source_identity(),
+ "selected_cases": selected,
+ "cases": [],
+ "cleanup": False,
+ }
+ try:
+ if artifacts is None:
+ artifacts, report["preflight"] = preflight(
+ output / "binaries", {CASES[case][0] for case in selected}
+ )
+ for case_id in selected:
+ kind, mode, test = CASES[case_id]
+ record = {
+ "case_id": case_id,
+ "mode": mode,
+ "cleanup": {},
+ "status": "NOT RUN",
+ }
+ report["cases"].append(record)
+ if kind not in artifacts:
+ record.update(
+ status="BLOCKED", reason="required official native peer unavailable"
+ )
+ continue
+ record["peer"] = artifacts[kind].identity
+ print(f"TROJAN: {case_id}", flush=True)
+ with (
+ tempfile.TemporaryDirectory(prefix="private-", dir=output) as directory,
+ contextlib.ExitStack() as stack,
+ ):
+ directory = Path(directory)
+ cert, key, pin = (
+ certificate_chain if mode.endswith("-ca") else certificates
+ )(directory)
+ port, reservation = reserve_port(stack)
+ password = " synthetic TROJAN 密码 "
+ config = peer_config(kind, mode, port, password, cert, key)
+ path = directory / "peer.json"
+ path.write_text(json.dumps(config))
+ node = {
+ "name": "peer",
+ "type": "trojan",
+ "server": "127.0.0.1",
+ "port": port,
+ "password": password,
+ "udp": True,
+ "sni": "localhost",
+ "fingerprint": pin,
+ }
+ if mode.startswith("ws"):
+ node.update(
+ network="ws",
+ **{
+ "ws-opts": {
+ "path": "/trojan-ws?q=1",
+ "headers": {
+ "Host": "cover.example:443",
+ "X-TROJAN": "fixture",
+ },
+ }
+ },
+ )
+ if mode.startswith("grpc"):
+ node.update(
+ network="grpc",
+ **{"grpc-opts": {"grpc-service-name": "trojan-grpc"}},
+ )
+ if mode.startswith("ws") and kind != "M":
+ node["ws-opts"]["path"] = "/trojan-ws/"
+ if mode in {"ws-ed-1", "ws-ed-2048", "ws-header", "ws-path"}:
+ node["ws-opts"]["max-early-data"] = 1 if mode == "ws-ed-1" else 2048
+ if mode in {"ws-header", "ws-path"}:
+ node["ws-opts"]["early-data-header-name"] = (
+ "x-vcore-ed" if mode == "ws-header" else ""
+ )
+ if mode == "ws-alpn":
+ node["alpn"] = ["h2", "http/1.1"]
+ if mode == "grpc-custom":
+ node["grpc-opts"]["grpc-service-name"] = "/trojan-grpc/Tun"
+ if mode.endswith("-ipv6"):
+ node["server"] = "::1"
+ command = (
+ [str(artifacts[kind].binary), "-d", str(directory), "-f", str(path)]
+ if kind == "M"
+ else [str(artifacts[kind].binary), "run", "-c", str(path)]
+ )
+ if mode.endswith("-ipv6"):
+ reservation.release_ipv6()
+ else:
+ reservation.release_ipv4()
+ with OwnedProcess(
+ command, directory / "peer.log", record["cleanup"]
+ ) as peer:
+ peer.wait_tcp(port, host=node["server"])
+ hop = None
+ if test == "public_trojan_native_policy_and_group_snapshots":
+ # Two independently owned peers, not one process proxying
+ # back into its own loopback detector.
+ hop_dir = directory / "hop"
+ hop_dir.mkdir()
+ hop_cert, hop_key, hop_pin = certificates(hop_dir)
+ hop_port, hop_reservation = reserve_port(stack)
+ hop_path = hop_dir / "peer.json"
+ hop_path.write_text(
+ json.dumps(
+ peer_config(
+ kind, mode, hop_port, password, hop_cert, hop_key
+ )
+ )
+ )
+ record["upstream_cleanup"] = {}
+ hop_reservation.release_ipv4()
+ hop_peer = stack.enter_context(
+ OwnedProcess(
+ [
+ str(artifacts[kind].binary),
+ "-d",
+ str(hop_dir),
+ "-f",
+ str(hop_path),
+ ],
+ hop_dir / "peer.log",
+ record["upstream_cleanup"],
+ )
+ )
+ hop_peer.wait_tcp(hop_port)
+ hop = dict(node, name="hop", port=hop_port, fingerprint=hop_pin)
+ env = dict(
+ os.environ,
+ VCORE_CASE_EVENTS=str(output / f"{case_id}-events.jsonl"),
+ VCORE_TROJAN_FIXTURE=json.dumps(
+ {
+ "node": node,
+ "hop": hop,
+ "mode": mode,
+ "udp_payload_max": 2048
+ if kind == "V2"
+ else 8166
+ if kind == "XR"
+ else 8192,
+ "data_dir": str(directory / "core"),
+ }
+ ),
+ )
+ target = (
+ "trojan_lifecycle"
+ if test == "trojan_native_owned_resources"
+ else "mihomo_interop"
+ )
+ test_name = (
+ test if target == "trojan_lifecycle" else f"trojan::{test}"
+ )
+ command = [
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ target,
+ test_name,
+ "--",
+ "--ignored",
+ "--exact",
+ "--nocapture",
+ ]
+ result = run_command(
+ command,
+ cwd=CORE_DIR,
+ env=env,
+ timeout=180,
+ limit=4 * 1024 * 1024,
+ )
+ (output / f"{case_id}.log").write_text(
+ redact(result.stdout.decode(errors="replace"))
+ )
+ record.update(
+ status="PASS"
+ if result.returncode == 0
+ and result.cleanup
+ and native_events_pass(
+ read_events(output / f"{case_id}-events.jsonl")
+ if (output / f"{case_id}-events.jsonl").exists()
+ else [],
+ test,
+ )
+ else "FAIL",
+ exit_code=result.returncode,
+ command_cleanup=result.cleanup,
+ seconds=result.seconds,
+ command=command,
+ )
+ peer.ensure_alive()
+ report["cleanup"] = all(
+ case["cleanup"].get("joined")
+ and case.get("upstream_cleanup", {"joined": True}).get("joined")
+ for case in report["cases"]
+ )
+ report["source_unchanged"] = (
+ source_identity()["source_tree_sha256"]
+ == report["source"]["source_tree_sha256"]
+ )
+ return (
+ 0
+ if report["cleanup"]
+ and report["source_unchanged"]
+ and all(case["status"] == "PASS" for case in report["cases"])
+ else 1
+ )
+ finally:
+ (output / "trojan-results.json").write_text(json.dumps(report, indent=2) + "\n")
diff --git a/scripts/src/vcore_scripts/protocol_trojan_acceptance.py b/scripts/src/vcore_scripts/protocol_trojan_acceptance.py
new file mode 100644
index 0000000..c3120b8
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_trojan_acceptance.py
@@ -0,0 +1,329 @@
+"""Trojan stage execution and independent, fail-closed persisted evidence checks."""
+
+from __future__ import annotations
+
+import json
+
+from .protocol_evidence import HEX, new_result, read_events, read_json, rust_results
+from .protocol_preflight import preflight
+from .protocol_trojan import native_events_pass
+from .protocol_trojan import run as run_native
+
+# Frozen independently of cases.json: removing or downgrading a case is not signoff.
+REQUIRED_IDS = {
+ "TROJAN-CODEC",
+ "TROJAN-CFG",
+ "TROJAN-CANCEL",
+ "TROJAN-M-TCP",
+ "TROJAN-M-WS",
+ "TROJAN-M-GRPC",
+ "TROJAN-M-WS-ED-1",
+ "TROJAN-M-WS-ED-2048",
+ "TROJAN-M-WS-POLICY",
+ "TROJAN-M-GRPC-POLICY",
+ "TROJAN-M-WS-NEGATIVE",
+ "TROJAN-M-GRPC-NEGATIVE",
+ "TROJAN-M-ALPN-NEGATIVE",
+ "TROJAN-V2-WS-HEADER",
+ "TROJAN-V2-WS-PATH",
+ "TROJAN-M-TCP-POLICY",
+ "TROJAN-XR-UDP-DOMAIN",
+ "TROJAN-XR-WS-UDP-DOMAIN",
+ "TROJAN-XR-GRPC-UDP-DOMAIN",
+ "TROJAN-M-TCP-LIFE",
+ "TROJAN-M-TCP-ENTRYPOINTS",
+ "TROJAN-M-TCP-UDP-ISOLATION",
+ "TROJAN-M-TCP-IPV6",
+ "TROJAN-M-TCP-OWNED",
+ "TROJAN-M-TCP-CERTIFICATE",
+ "TROJAN-M-WS-LIFE",
+ "TROJAN-M-WS-ENTRYPOINTS",
+ "TROJAN-M-WS-UDP-ISOLATION",
+ "TROJAN-M-WS-IPV6",
+ "TROJAN-M-WS-OWNED",
+ "TROJAN-M-WS-CERTIFICATE",
+ "TROJAN-M-GRPC-LIFE",
+ "TROJAN-M-GRPC-ENTRYPOINTS",
+ "TROJAN-M-GRPC-UDP-ISOLATION",
+ "TROJAN-M-GRPC-IPV6",
+ "TROJAN-M-GRPC-OWNED",
+ "TROJAN-M-GRPC-CERTIFICATE",
+ "TROJAN-M-GRPC-CUSTOM",
+ "TROJAN-FEATURES",
+ "TROJAN-SCRIPTS",
+ "TROJAN-REGRESSION",
+}
+FIELD_IDS = {
+ "C01",
+ "C02",
+ "C03",
+ "C04",
+ "C05",
+ "C06",
+ "T01",
+ "T03",
+ "T04",
+ "T05",
+ "W01",
+ "W02",
+ "W03",
+ "W04",
+ "W05",
+ "G01",
+ "TR01",
+ "TR02",
+}
+
+
+def native_results(cases, report, directory):
+ records = report.get("cases", [])
+ if [entry.get("case_id") for entry in records] != [
+ case["case_id"] for case in cases
+ ]:
+ raise ValueError("missing, duplicate or reordered Trojan native evidence")
+ results = []
+ for case, record in zip(cases, records, strict=True):
+ path = directory / (case["case_id"] + "-events.jsonl")
+ events = read_events(path) if path.exists() else []
+ observed = native_events_pass(events, case["peer_config"]["test"])
+ clean = (
+ record.get("command_cleanup") is True
+ and record.get("cleanup", {}).get("joined") is True
+ and record.get("upstream_cleanup", {"joined": True}).get("joined") is True
+ )
+ passed = (
+ observed
+ and clean
+ and record.get("exit_code") == 0
+ and record.get("status") == "PASS"
+ and record.get("mode") == case["peer_config"]["mode"]
+ and report.get("source_unchanged") is True
+ )
+ result = new_result(case)
+ result.update(
+ status="PASS" if passed else "FAIL",
+ assertions={name: observed for name in case["expected_observation"]},
+ evidence=case["required_evidence"] if passed else [],
+ command_exit_code=record.get("exit_code"),
+ cleanup=clean,
+ )
+ results.append(result)
+ return results
+
+
+def fields_report(cases, results):
+ statuses = {result["case_id"]: result["status"] for result in results}
+ complete = {case["case_id"] for case in cases} == REQUIRED_IDS
+ return {
+ "schema_version": 1,
+ "stage": "TROJAN",
+ "protocol": "trojan",
+ "scope": "protocol-consumer; other protocols remain NOT RUN",
+ "fields": [
+ {
+ "row_id": row,
+ "status": "PASS"
+ if complete
+ and owners
+ and all(statuses.get(case_id) == "PASS" for case_id in owners)
+ else "NOT RUN",
+ "required_cases": owners,
+ }
+ for row in sorted(FIELD_IDS)
+ for owners in [
+ [case["case_id"] for case in cases if row in case["row_ids"]]
+ ]
+ ],
+ "peer_limitations": [
+ "Mihomo v1.19.31 domain UDP FAIL is retained; "
+ "Xray TCP/WS/gRPC supplies separate domain evidence.",
+ "V2Ray ED supplement UDP path is bounded by its 2048-byte return buffer; "
+ "8192-byte truncation is retained as peer failure.",
+ "Xray domain UDP return frame has 8192 total bytes, "
+ "leaving 8166 payload for the controlled domain; "
+ "larger peer failure retained.",
+ ],
+ }
+
+
+def execute(cases, run, output, records):
+ from .protocol_harness import _command, _events, _features, _legacy, _scripts
+
+ rust = [case for case in cases if case["runner"] == "rust"]
+ if rust:
+ command = _command(
+ run,
+ output,
+ "rust-consumer",
+ ["cargo", "test", "--locked", "--all-features", "--all-targets"],
+ 600,
+ events=output / "rust-events.jsonl",
+ )
+ events = _events(output / "rust-events.jsonl")
+ for case in rust:
+ result = rust_results(case, events, command.returncode)
+ result["cleanup"] = command.cleanup
+ records[case["case_id"]] = result
+ kinds = {case["peer_kind"] for case in cases if case["peer_kind"] != "unit"}
+ artifacts, peers = preflight(
+ output / "binaries",
+ kinds,
+ container=any(case["runner"] == "mihomo-legacy" for case in cases),
+ )
+ (output / "peers.json").write_text(json.dumps(peers, indent=2) + "\n")
+ native = [case for case in cases if case["runner"] == "native-trojan"]
+ if native:
+ directory = output / "native"
+ run_native(directory, [case["case_id"] for case in native], artifacts=artifacts)
+ report = read_json(directory / "trojan-results.json")
+ for result in native_results(native, report, directory):
+ records[result["case_id"]] = result
+ for case in cases:
+ if case["runner"] == "features":
+ records[case["case_id"]] = _features(case, run, output)
+ elif case["runner"] == "scripts":
+ records[case["case_id"]] = _scripts(case, run, output)
+ elif case["runner"] == "mihomo-legacy":
+ records[case["case_id"]] = _legacy(case, run, output, artifacts)
+ (output / "fields.json").write_text(
+ json.dumps(fields_report(cases, list(records.values())), indent=2) + "\n"
+ )
+
+
+def check(run_dir, required, run, results, peers, paths):
+ from .protocol_harness import SCRIPT_OBSERVATIONS
+
+ necessary = {
+ "cases.json",
+ "peers.json",
+ "resources.jsonl",
+ "summary.md",
+ "rust-events.jsonl",
+ "legacy-events.jsonl",
+ "script-tests.json",
+ "native/trojan-results.json",
+ "fields.json",
+ }
+ if not necessary <= set(paths):
+ raise ValueError("missing Trojan acceptance artifacts")
+ expected_commands = {
+ "rust-consumer",
+ "legacy-mihomo",
+ "offline-scripts",
+ "feature-default",
+ "feature-minimal",
+ "feature-outbound-trojan",
+ "feature-outbound-vmess",
+ "feature-outbound-hysteria2",
+ "feature-stream-transport",
+ "feature-quic-transport",
+ }
+ commands = run.get("commands", [])
+ if (
+ len(commands) != len(expected_commands)
+ or {command.get("name") for command in commands} != expected_commands
+ or any(
+ type(command.get("exit_code")) is not int
+ or command["exit_code"] != 0
+ or command.get("cleanup") is not True
+ or (command.get("log") and command["log"] not in paths)
+ for command in commands
+ )
+ ):
+ raise ValueError("missing, failed or unjoined Trojan acceptance command")
+ native = [case for case in required if case["runner"] == "native-trojan"]
+ report = read_json(run_dir / "native/trojan-results.json")
+ if (
+ report.get("source_unchanged") is not True
+ or report.get("cleanup") is not True
+ or report.get("source", {}).get("source_tree_sha256")
+ != run["source_tree_sha256"]
+ or report.get("source", {}).get("lock_sha256") != run["lock_sha256"]
+ ):
+ raise ValueError("Trojan peer tests used another source input")
+ for record, case in zip(report.get("cases", []), native, strict=True):
+ for suffix in (".log", "-events.jsonl"):
+ if "native/" + case["case_id"] + suffix not in paths:
+ raise ValueError("native log/events missing immutable identity")
+ identity = [peer for peer in peers if peer.get("kind") == case["peer_kind"]]
+ if (
+ len(identity) != 1
+ or identity[0].get("status") != "READY"
+ or not identity[0].get("version")
+ or not HEX.fullmatch(identity[0].get("binary_sha256", ""))
+ or not HEX.fullmatch(identity[0].get("archive_sha256", ""))
+ or not identity[0].get("source_url", "").startswith("https://github.com/")
+ or any(
+ record.get("peer", {}).get(key) != identity[0].get(key)
+ for key in ("version", "binary_sha256", "archive_sha256", "source_url")
+ )
+ ):
+ raise ValueError("Trojan used a peer different from official preflight")
+ test = case["peer_config"]["test"]
+ target = (
+ "trojan_lifecycle"
+ if test == "trojan_native_owned_resources"
+ else "mihomo_interop"
+ )
+ name = test if target == "trojan_lifecycle" else "trojan::" + test
+ if record.get("command") != [
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ target,
+ name,
+ "--",
+ "--ignored",
+ "--exact",
+ "--nocapture",
+ ]:
+ raise ValueError("Trojan case did not execute its declared public consumer")
+ calculated = native_results(native, report, run_dir / "native")
+ rust = read_events(run_dir / "rust-events.jsonl")
+ legacy = read_events(run_dir / "legacy-events.jsonl")
+ for case in required:
+ if case["runner"] in {"rust", "mihomo-legacy"}:
+ entry = rust_results(
+ case, legacy if case["runner"] == "mihomo-legacy" else rust, 0
+ )
+ if case["runner"] == "mihomo-legacy" and entry["status"] == "PASS":
+ entry["evidence"] = case["required_evidence"]
+ calculated.append(entry)
+ actual = {entry["case_id"]: entry for entry in results}
+ for entry in calculated:
+ if actual[entry["case_id"]] != entry:
+ raise ValueError(
+ "Trojan result disagrees with original structured assertions"
+ )
+ script = read_json(run_dir / "script-tests.json")
+ tests = {entry["test"]: entry["status"] for entry in script.get("cases", [])}
+ if (
+ not tests
+ or len(tests) != len(script.get("cases", []))
+ or len(tests) != script.get("tests_run")
+ or any(status != "PASS" for status in tests.values())
+ or any(tests.get(name) != "PASS" for name in SCRIPT_OBSERVATIONS.values())
+ or not any("test_protocol_trojan." in name for name in tests)
+ ):
+ raise ValueError("Trojan harness failure paths were not exercised")
+ mihomo = next(peer for peer in peers if peer["kind"] == "M")
+ if (
+ mihomo.get("container_status") != "READY"
+ or not HEX.fullmatch(
+ mihomo.get("container_artifact", {}).get("binary_sha256", "")
+ )
+ or mihomo["container_artifact"].get("release") != mihomo.get("release")
+ ):
+ raise ValueError("old regression did not use the same official Mihomo snapshot")
+ field_report = fields_report(required, results)
+ if read_json(run_dir / "fields.json") != field_report or any(
+ row["status"] != "PASS" for row in field_report["fields"]
+ ):
+ raise ValueError("incomplete or inconsistent Trojan field report")
+ print(
+ f"TROJAN: PASS ({len(required)} required cases, "
+ f"{len(FIELD_IDS)} Trojan fields); "
+ "other protocols remain NOT RUN"
+ )
diff --git a/scripts/src/vcore_scripts/protocol_vless.py b/scripts/src/vcore_scripts/protocol_vless.py
new file mode 100644
index 0000000..363f1a3
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_vless.py
@@ -0,0 +1,27 @@
+"""VLESS development mode selection, using the same container fixtures as acceptance.
+
+This entry does not execute local/build gates or sign off the complete stage.
+"""
+
+from pathlib import Path
+
+from .protocol_vless_container import run as run_cases
+from .protocol_vless_peers import MODES
+from .protocol_vless_public import CASES
+
+
+def run(output: Path, modes=None):
+ modes = MODES if modes is None else modes
+ if not modes or not set(modes) <= set(MODES) or len(set(modes)) != len(modes):
+ raise ValueError("invalid VLESS development mode")
+ selected = [case for case, (_, mode, _, _) in CASES.items() if mode in modes]
+ return run_cases(output, selected)
+
+
+if __name__ == "__main__":
+ import sys
+
+ from .mihomo_isolation import exclusive_run
+
+ with exclusive_run():
+ sys.exit(run(Path(sys.argv[1]).resolve(), sys.argv[2:] or None))
diff --git a/scripts/src/vcore_scripts/protocol_vless_acceptance.py b/scripts/src/vcore_scripts/protocol_vless_acceptance.py
new file mode 100644
index 0000000..8b80e85
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_vless_acceptance.py
@@ -0,0 +1,652 @@
+"""VLESS container-only public consumer acceptance and independent coverage."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from .builds import DEFAULT_FEATURES
+from .protocol_evidence import HEX, idle_resources, new_result, read_events, read_json
+from .protocol_inputs import redact
+from .protocol_vless_container import run as native_run
+from .protocol_vless_public import PUBLIC, WIRE, events_pass
+from .protocol_vmess_acceptance import OBSERVATIONS as PREVIOUS_OBSERVATIONS
+from .protocol_vmess_acceptance import SCRIPT_ASSERTIONS
+
+NATIVE = WIRE | PUBLIC
+FIELD_IDS = {
+ *(f"C{i:02}" for i in range(1, 7)),
+ *(f"T{i:02}" for i in range(2, 9)),
+ *(f"W{i:02}" for i in range(1, 8)),
+ *(f"G{i:02}" for i in range(1, 7)),
+ *(f"H{i:02}" for i in range(1, 7)),
+ *(f"VL{i:02}" for i in range(1, 6)),
+ "S01",
+ "S02",
+}
+GATES = {
+ "VLESS-CFG",
+ "VLESS-CODEC",
+ "VLESS-TRANSPORT",
+ "VLESS-VISION",
+ "VLESS-REGRESSION",
+ "VLESS-RELEASE",
+ "VLESS-FEATURES",
+ "VLESS-SCRIPTS",
+ "VLESS-QUALITY",
+}
+REQUIRED_IDS = set(NATIVE) | GATES
+OBSERVATIONS = {
+ "VLESS-CFG": [
+ "inline_client_identity_is_validated_and_redacted_before_io",
+ "vision_requires_tcp_tls13_and_xudp_before_any_io",
+ "default_tcp_and_three_udp_encodings_are_accepted_without_io",
+ "tcp_and_existing_xhttp_reject_mismatched_and_future_options",
+ "stream_transports_and_explicit_tls_policy_have_strict_public_fields",
+ "extended_ws_and_grpc_fields_are_scoped_and_bounded",
+ ],
+ "VLESS-CODEC": [
+ "stopping_before_first_udp_send_wakes_receive_and_releases_io",
+ "raw_and_packetaddr_consume_wire_and_keep_cancelled_receive_progress",
+ "udp_cancelled_send_and_bad_response_header_close_owned_io",
+ "tcp_bad_response_header_poisoning_and_absolute_response_deadline",
+ "vless_all_handshakes_keep_the_original_deadline_and_join_cancelled_io",
+ "vless_expired_deadline_and_protect_failure_never_fall_back",
+ ],
+ "VLESS-TRANSPORT": [
+ "http_camouflage_shutdown_releases_both_directions_without_waiting_for_peer_eof",
+ "grpc_server_first_flushes_vless_request_without_an_application_write",
+ "http_upgrade_consumes_early_prefix_and_requires_valid_101_even_fast_open",
+ "grpc_idle_ping_is_observable_disabled_by_zero_and_joined_at_stop",
+ "grpc_pool_matches_both_threshold_policies_and_keeps_other_streams_alive",
+ ],
+ "VLESS-VISION": [
+ "vision_fragmented_headers_content_padding_and_cancelled_reads_keep_raw_tail",
+ "vision_invalid_uuid_command_and_truncation_poison_the_stream",
+ "vision_bounded_partial_writes_flush_and_close_preserve_all_plaintext",
+ "fragmented_server_hello_distinguishes_tls12_tls13_and_non_tls",
+ "record_boundary_preserves_buffered_plaintext_and_coalesced_raw_tail_and_flush_order",
+ ],
+}
+OBSERVATIONS["VLESS-REGRESSION"] = (
+ PREVIOUS_OBSERVATIONS["VMESS-REGRESSION"]
+ + PREVIOUS_OBSERVATIONS["VMESS-CFG"]
+ + PREVIOUS_OBSERVATIONS["VMESS-CODEC"]
+ + PREVIOUS_OBSERVATIONS["VMESS-CANCEL"]
+ + [
+ "all_two_hop_protocol_combinations_build_as_connector_graphs",
+ "direct_download_constructor_reuses_or_requires_the_precise_prepared_endpoint",
+ "split_node_over_a_proxy_automatically_reuses_its_parent_for_both_legs",
+ ]
+)
+OBSERVATIONS["VLESS-RELEASE"] = sum(
+ (
+ OBSERVATIONS[key]
+ for key in ("VLESS-CFG", "VLESS-CODEC", "VLESS-TRANSPORT", "VLESS-VISION")
+ ),
+ [],
+)
+
+
+def rows(identifier):
+ if identifier == "VLESS-CFG":
+ return sorted(FIELD_IDS)
+ if identifier == "VLESS-CODEC":
+ return ["VL01", "VL02", "VL04"]
+ if identifier == "VLESS-TRANSPORT":
+ return [*(f"G{i:02}" for i in range(1, 7)), "W06", "W07"]
+ if identifier == "VLESS-VISION":
+ return ["VL03", "VL04", "VL05", "S01", "S02"]
+ if identifier in GATES or identifier.startswith("VLESS-REGRESSION"):
+ return []
+ _, mode, tls, test = NATIVE[identifier]
+ result = {"VL01", "VL02", "VL04", "VL05"}
+ if identifier in PUBLIC:
+ result |= {*(f"C{i:02}" for i in range(1, 6))}
+ if "graph" in test or "selection" in test:
+ result.add("C06")
+ if mode.endswith("-reality"):
+ result |= {"S01", "S02", "T02"}
+ elif tls:
+ result |= {"T02", "T03", "T04", "T05"}
+ if mode.endswith("-mtls"):
+ result |= {"T06", "T07", "T08"}
+ if mode.startswith("vision-"):
+ result.add("VL03")
+ if mode.startswith(("ws", "upgrade")):
+ result |= {*(f"W{i:02}" for i in range(1, 6))}
+ if mode.startswith("upgrade"):
+ result |= {"W06", "W07"}
+ if mode.startswith("grpc"):
+ result |= {*(f"G{i:02}" for i in range(1, 7))}
+ if mode.startswith("http"):
+ result |= {"H01", "H02", "H03", "H04"}
+ if mode.startswith("h2"):
+ result |= {"H05", "H06"}
+ return sorted(result)
+
+
+def definitions():
+ cases = []
+ for identifier in sorted(REQUIRED_IDS):
+ kind, mode, tls, test = NATIVE.get(
+ identifier, ("unit", "memory-or-build", False, identifier)
+ )
+ native = identifier in NATIVE
+ substage = (
+ "VLESS.vision"
+ if mode.startswith("vision-") or identifier == "VLESS-VISION"
+ else "VLESS.tcp"
+ if mode in {"tcp", "tcp-tls"} or identifier == "VLESS-CODEC"
+ else "VLESS.transports"
+ if mode.startswith(("ws", "grpc", "http", "h2", "upgrade"))
+ or identifier == "VLESS-TRANSPORT"
+ else "VLESS.acceptance"
+ )
+ cases.append(
+ dict(
+ case_id=identifier,
+ stage="VLESS",
+ substage=substage,
+ required=True,
+ row_ids=rows(identifier),
+ protocol="vless",
+ network=mode,
+ security="tls" if tls else "plain",
+ udp_codec="raw/xudp/packetaddr"
+ if "udp" in test or test == "public_base"
+ else "per-assertion",
+ field_values={
+ "network": mode,
+ "tls": tls,
+ "scope": "protocol-consumer",
+ "close_reference": "ws-standard-tls-baseline"
+ if test == "native_ws_reality_close_boundary"
+ else "same-mode"
+ if test == "native_mihomo_close_alignment"
+ else "not-applicable",
+ },
+ outer_family="IPv4/IPv6" if "ipv6" in test else "IPv4",
+ inner_family="IPv4/IPv6/domain"
+ if "base" in test or "udp_boundaries" in test
+ else "per-assertion",
+ target_type="isolated synthetic origin" if native else "memory-only",
+ upstream_graph="direct/concrete/nested-select"
+ if "graph" in test
+ else "per-assertion",
+ peer_kind=kind,
+ peer_config=dict(mode=mode, tls=tls, test=test),
+ gap_source={
+ "reason": "Mihomo WS client ignores RealityOpts; "
+ "REALITY listener data "
+ "is native-tested, but close uses the separate standard-TLS WS "
+ "adapter reference plus independent REALITY close cases, not a "
+ "same-combination client differential. Original failures retained.",
+ "source": "https://github.com/MetaCubeX/mihomo/blob/ab405bad5beeeac8b003bb01f60f134f6df54471/adapter/outbound/vless.go",
+ }
+ if test == "native_ws_reality_close_boundary"
+ else {
+ "reason": "Mihomo VLESS listener has no HTTP header/legacy H2 "
+ "or custom ED field; official V2Ray supplements only these paths",
+ "source": "https://github.com/MetaCubeX/mihomo/blob/v1.19.31/listener/inbound/vless.go",
+ }
+ if kind == "V2"
+ else None,
+ expected_observation=[test]
+ if native
+ else SCRIPT_ASSERTIONS
+ if identifier == "VLESS-SCRIPTS"
+ else OBSERVATIONS.get(identifier, [identifier]),
+ required_evidence=["structured-assertions", "command", "cleanup"]
+ + (["peer-identity", "isolated-origins"] if native else []),
+ prerequisites=[
+ "owned-host-only-container-network",
+ "official-latest-peer",
+ ]
+ if native
+ else ["rust-toolchain"],
+ runner="native-vless" if native else "vless-gate",
+ timeout_seconds=240 if native else 1200,
+ )
+ )
+ return cases
+
+
+def commands(identifier):
+ cargo = ["cargo", "test", "--locked", "--all-features"]
+ if identifier == "VLESS-CFG":
+ return [cargo + ["--test", "vless_config"], cargo + ["--lib", "config::"]]
+ if identifier == "VLESS-CODEC":
+ return [cargo + ["--test", "vless_codec", "--test", "vless_lifecycle"]]
+ if identifier == "VLESS-TRANSPORT":
+ return [cargo + ["--test", "vless_transports", "--test", "grpc_pool"]]
+ if identifier == "VLESS-VISION":
+ return [cargo + ["--lib", "vision"]]
+ if identifier == "VLESS-RELEASE":
+ return [
+ cargo
+ + [
+ "--release",
+ "--test",
+ "vless_config",
+ "--test",
+ "vless_codec",
+ "--test",
+ "vless_lifecycle",
+ "--test",
+ "vless_transports",
+ "--test",
+ "grpc_pool",
+ ],
+ cargo + ["--release", "--lib", "vision"],
+ ]
+ if identifier == "VLESS-REGRESSION":
+ from .protocol_vmess_acceptance import commands as previous
+
+ return (
+ previous("VMESS-REGRESSION")
+ + previous("VMESS-CFG")
+ + previous("VMESS-CODEC")
+ + previous("VMESS-CANCEL")
+ + [
+ cargo
+ + ["--lib", "outbound::vless::outbound::connector_composition_tests::"]
+ ]
+ + [
+ ["cargo", "test", "--locked", "--no-default-features"]
+ + features
+ + [
+ "--test",
+ "feature_foundations",
+ "vless_yaml_follows_its_own_feature",
+ "--",
+ "--exact",
+ ]
+ for features in ([], ["--features", "outbound-trojan"])
+ ]
+ )
+ if identifier == "VLESS-QUALITY":
+ from .protocol_vmess_acceptance import commands as previous
+
+ return previous("VMESS-QUALITY")
+ return []
+
+
+def gate_result(case, records, events):
+ result = new_result(case)
+ good = bool(records) and all(
+ r.get("exit_code") == 0 and r.get("cleanup") is True for r in records
+ )
+ identifier = case["case_id"]
+ assertions = {}
+ if identifier in OBSERVATIONS:
+ for name in case["expected_observation"]:
+ observed = [e for e in events if e.get("assertion") == name]
+ assertions[name] = len(observed) == 2 and [
+ e.get("status") for e in observed
+ ] == ["BEGIN", "PASS"]
+ good &= (
+ bool(assertions)
+ and all(assertions.values())
+ and all(
+ e.get("schema_version") == 1 and e.get("status") in {"BEGIN", "PASS"}
+ for e in events
+ )
+ )
+ else:
+ assertions = dict.fromkeys(case["expected_observation"], good)
+ result.update(
+ status="PASS" if good else "FAIL",
+ assertions=assertions,
+ evidence=case["required_evidence"] if good else [],
+ command_exit_code=0 if good else 1,
+ cleanup=all(r.get("cleanup") is True for r in records),
+ )
+ return result
+
+
+def native_results(cases, report, directory):
+ records = report.get("cases", [])
+ expected = {case["case_id"] for case in cases}
+ if len(records) != len(expected) or {r.get("case_id") for r in records} != expected:
+ raise ValueError("missing, duplicate or unknown VLESS native case")
+ by_id = {record["case_id"]: record for record in records}
+ output = []
+ for case in cases:
+ record = by_id[case["case_id"]]
+ path = directory / (case["case_id"] + "-events.jsonl")
+ observed = read_events(path) if path.exists() else []
+ test = NATIVE[case["case_id"]][3]
+ observed_ok = (
+ events_pass(observed, test, NATIVE[case["case_id"]][1])
+ if case["case_id"] in PUBLIC
+ else observed
+ == [
+ dict(
+ schema_version=1, suite="VLESS-WIRE", assertion=test, status=status
+ )
+ for status in ("BEGIN", "PASS")
+ ]
+ )
+ clean = (
+ record.get("command_cleanup") is True
+ and record.get("cleanup") is True
+ and report.get("cleanup") is True
+ )
+ expected_command = [
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ "vless_public" if case["case_id"] in PUBLIC else "vless_native",
+ test,
+ "--",
+ "--ignored",
+ "--exact",
+ "--nocapture",
+ ]
+ good = (
+ observed_ok
+ and clean
+ and report.get("source_unchanged") is True
+ and record.get("exit_code") == 0
+ and record.get("status") == "PASS"
+ and record.get("command") == expected_command
+ and record.get("peer_kind") == case["peer_kind"]
+ )
+ result = new_result(case)
+ result.update(
+ status="PASS" if good else "FAIL",
+ assertions={test: observed_ok},
+ evidence=case["required_evidence"] if good else [],
+ command_exit_code=record.get("exit_code"),
+ cleanup=clean,
+ )
+ output.append(result)
+ return output
+
+
+def fields_report(cases, results):
+ statuses = {result["case_id"]: result["status"] for result in results}
+ complete = set(statuses) == REQUIRED_IDS and all(
+ value == "PASS" for value in statuses.values()
+ )
+ fields = []
+ for row in sorted(FIELD_IDS):
+ owners = [c["case_id"] for c in cases if row in c["row_ids"]]
+ fields.append(
+ dict(
+ row_id=row,
+ required_cases=owners,
+ status="PASS" if complete and len(owners) > 1 else "NOT RUN",
+ )
+ )
+ return dict(schema_version=1, stage="VLESS", protocol="vless", fields=fields)
+
+
+def execute(cases, run, output, results):
+ from .protocol_harness import _command, _features, _scripts
+
+ for case in cases:
+ identifier = case["case_id"]
+ if identifier in NATIVE:
+ continue
+ if identifier == "VLESS-FEATURES":
+ result = _features(case, run, output)
+ independent = _command(
+ run,
+ output,
+ "feature-outbound-vless",
+ [
+ "cargo",
+ "check",
+ "--locked",
+ "--no-default-features",
+ "--lib",
+ "--features",
+ "outbound-vless",
+ ],
+ 1200,
+ )
+ if independent.returncode or not independent.cleanup:
+ result.update(
+ status="FAIL",
+ command_exit_code=independent.returncode,
+ cleanup=independent.cleanup,
+ )
+ build = _command(
+ run,
+ output,
+ "production-build",
+ [
+ "cargo",
+ "build",
+ "--locked",
+ "--release",
+ "--no-default-features",
+ "--features",
+ DEFAULT_FEATURES,
+ "--lib",
+ ],
+ 1200,
+ )
+ if build.returncode or not build.cleanup:
+ result.update(
+ status="FAIL",
+ command_exit_code=build.returncode,
+ cleanup=build.cleanup,
+ )
+ results[identifier] = result
+ elif identifier == "VLESS-SCRIPTS":
+ results[identifier] = _scripts(case, run, output)
+ else:
+ events = []
+ start = len(run["commands"])
+ for index, argv in enumerate(commands(identifier)):
+ path = output / f"{identifier}-{index}-events.jsonl"
+ _command(run, output, f"{identifier}-{index}", argv, 1200, events=path)
+ if path.exists():
+ events.extend(read_events(path))
+ results[identifier] = gate_result(case, run["commands"][start:], events)
+ native = [case for case in cases if case["case_id"] in NATIVE]
+ if native:
+ directory = output / "native"
+ native_run(directory, [case["case_id"] for case in native])
+ report = read_json(directory / "vless-results.json")
+ (output / "peers.json").write_text(json.dumps(report["peers"], indent=2) + "\n")
+ for result in native_results(native, report, directory):
+ results[result["case_id"]] = result
+ (output / "fields.json").write_text(
+ json.dumps(fields_report(cases, list(results.values())), indent=2) + "\n"
+ )
+
+
+def required_command_names():
+ # The shared feature smoke includes VMess; VLESS separately adds VLESS.
+ return {
+ f"{identifier}-{i}"
+ for identifier in GATES
+ for i in range(len(commands(identifier)))
+ } | {
+ "production-build",
+ "offline-scripts",
+ "feature-default",
+ "feature-minimal",
+ "feature-outbound-vless",
+ *(
+ "feature-" + name
+ for name in (
+ "outbound-trojan",
+ "outbound-vmess",
+ "outbound-hysteria2",
+ "stream-transport",
+ "quic-transport",
+ )
+ ),
+ }
+
+
+def check(run_dir, cases, run, results, peers, paths):
+ from .protocol_harness import SCRIPT_OBSERVATIONS
+
+ needed = {
+ "native/vless-results.json",
+ "fields.json",
+ "script-tests.json",
+ "resources.jsonl",
+ "peers.json",
+ "cases.json",
+ "summary.md",
+ }
+ if not needed <= set(paths):
+ raise ValueError("missing VLESS acceptance artifacts")
+ expected = {c["case_id"]: c for c in definitions()}
+ if len(cases) != len(expected) or any(
+ c != expected.get(c["case_id"]) for c in cases
+ ):
+ raise ValueError("VLESS frozen case metadata changed")
+ report = read_json(run_dir / "native/vless-results.json")
+ source_keys = (
+ "parent_commit",
+ "source_tree_sha256",
+ "dirty_patch_sha256",
+ "lock_sha256",
+ )
+ if (
+ report.get("source") != {key: run.get(key) for key in source_keys}
+ or report.get("status") != "PASS"
+ ):
+ raise ValueError("VLESS peer evidence input mismatch")
+ isolation = report.get("isolation", {})
+ if (
+ isolation.get("host_servers") is not False
+ or isolation.get("network_mode") != "hostOnly"
+ or not isolation.get("peers")
+ or not all(
+ p.get("joined") is True and p.get("started") is True
+ for p in isolation["peers"]
+ )
+ ):
+ raise ValueError("VLESS peers not isolated or cleaned")
+ if peers != report.get("peers") or set(peers) != {"M", "V2"}:
+ raise ValueError("missing VLESS official peers")
+ for kind, peer in peers.items():
+ project = "MetaCubeX/mihomo" if kind == "M" else "v2fly/v2ray-core"
+ if (
+ peer.get("kind") != kind
+ or peer.get("target") != "linux-arm64"
+ or not peer.get("version")
+ or not peer.get("source_url", "").startswith(
+ f"https://github.com/{project}/releases/"
+ )
+ or not all(
+ HEX.fullmatch(peer.get(key, ""))
+ for key in ("archive_sha256", "binary_sha256")
+ )
+ ):
+ raise ValueError("invalid official VLESS peer identity")
+ actual = {r["case_id"]: r for r in results}
+ recalculated = native_results(
+ [c for c in cases if c["case_id"] in NATIVE], report, run_dir / "native"
+ )
+ for case in cases:
+ identifier = case["case_id"]
+ argv = commands(identifier)
+ if not argv:
+ continue
+ records = []
+ events = []
+ for i, command in enumerate(argv):
+ matching = [r for r in run["commands"] if r["name"] == f"{identifier}-{i}"]
+ if len(matching) != 1 or matching[0]["command"] != [
+ redact(part) for part in command
+ ]:
+ raise ValueError("missing VLESS gate command")
+ records.extend(matching)
+ path = run_dir / f"{identifier}-{i}-events.jsonl"
+ if path.exists():
+ events.extend(read_events(path))
+ recalculated.append(gate_result(case, records, events))
+ for item in recalculated:
+ if item != actual.get(item["case_id"]):
+ raise ValueError("VLESS results disagree with structured observations")
+ names = [c["name"] for c in run["commands"]]
+ needed_commands = required_command_names()
+ if (
+ len(names) != len(set(names))
+ or set(names) != needed_commands
+ or any(
+ c.get("exit_code") != 0
+ or c.get("cleanup") is not True
+ or c.get("log") not in paths
+ for c in run["commands"]
+ )
+ ):
+ raise ValueError("missing or failed VLESS validation command")
+ for record in run["commands"]:
+ name = record["name"]
+ if name == "feature-default":
+ expected_command = [
+ "cargo",
+ "test",
+ "--locked",
+ "--test",
+ "feature_foundations",
+ ]
+ elif name.startswith("feature-"):
+ expected_command = [
+ "cargo",
+ "check",
+ "--locked",
+ "--no-default-features",
+ "--lib",
+ ]
+ if name != "feature-minimal":
+ expected_command += ["--features", name.removeprefix("feature-")]
+ elif name == "production-build":
+ expected_command = [
+ "cargo",
+ "build",
+ "--locked",
+ "--release",
+ "--no-default-features",
+ "--features",
+ DEFAULT_FEATURES,
+ "--lib",
+ ]
+ elif name == "offline-scripts":
+ expected_command = [
+ sys.executable,
+ "-m",
+ "vcore_scripts.protocol_script_tests",
+ str(run_dir / "script-tests.json"),
+ ]
+ else:
+ continue
+ if record["command"] != [redact(part) for part in expected_command]:
+ raise ValueError("VLESS feature or script command changed")
+ script = read_json(run_dir / "script-tests.json")
+ tests = {t["test"]: t["status"] for t in script["cases"]}
+ if (
+ len(tests) != script["tests_run"]
+ or any(tests.get(name) != "PASS" for name in SCRIPT_OBSERVATIONS.values())
+ or any(status != "PASS" for status in tests.values())
+ ):
+ raise ValueError("missing harness failure-path tests")
+ fields = fields_report(cases, results)
+ if read_json(run_dir / "fields.json") != fields or any(
+ f["status"] != "PASS" for f in fields["fields"]
+ ):
+ raise ValueError("incomplete VLESS field coverage")
+ resources = read_events(run_dir / "resources.jsonl")
+ owned = [
+ e
+ for e in resources
+ if e.get("suite") == "VLESS-OWNED" and e.get("status") == "PASS"
+ ]
+ if len(owned) != 80 or not all(idle_resources(e.get("resources")) for e in owned):
+ raise ValueError("missing 20-round owned resource evidence per selected mode")
+ print(
+ f"VLESS: PASS ({len(cases)} required cases; {len(FIELD_IDS)} VLESS field rows)"
+ )
diff --git a/scripts/src/vcore_scripts/protocol_vless_container.py b/scripts/src/vcore_scripts/protocol_vless_container.py
new file mode 100644
index 0000000..d91120c
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_vless_container.py
@@ -0,0 +1,759 @@
+"""VLESS wire cases against official latest peers and entirely isolated origins."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import shutil
+import ssl
+import tempfile
+from pathlib import Path
+
+from .builds import CORE_DIR
+from .mihomo_release import download_mihomo
+from .native_release import PeerArtifact, download_native
+from .protocol_containers import ContainerLab, command
+from .protocol_evidence import read_events
+from .protocol_fixtures import certificates
+from .protocol_inputs import redact, source_identity
+from .protocol_peers import run_command
+from .protocol_vless_peers import configuration
+from .protocol_vless_public import PUBLIC as PUBLIC_CASES
+from .protocol_vless_public import WIRE as CASES
+from .protocol_vless_public import events_pass
+from .protocol_vless_security import client_identities
+from .protocol_vmess import peer_config as legacy_peer
+from .protocol_vmess_public import node_config as legacy_node
+
+ALL_CASES = CASES | PUBLIC_CASES
+CLOSE_TESTS = {
+ "native_mihomo_close_alignment",
+ "native_ws_reality_close_boundary",
+ "native_vision_direct_close_alignment",
+}
+CLIENT_FINGERPRINTS = (
+ "none",
+ "chrome",
+ "chrome120",
+ "firefox",
+ "firefox120",
+ "safari",
+ "safari16",
+)
+
+
+def close_reference(mode, node, config, certificate, private_key, pin):
+ reference = dict(node, name="reference")
+ if reference.get("network") == "ws":
+ options = dict(reference.get("ws-opts", {}))
+ if options.get("max-early-data", 0) > 0:
+ # VCore defaults ED to this header; Mihomo's raw option defaults
+ # to path ED. Explicit empty/custom values must stay unchanged.
+ options.setdefault("early-data-header-name", "Sec-WebSocket-Protocol")
+ reference["ws-opts"] = options
+ scope = "same-mode"
+ if mode.endswith("-reality") and reference.get("network") == "ws":
+ # Mihomo's WS client never consumes RealityOpts. Its REALITY listener
+ # does support WS, so preserve VCore's real peer and compare the WS
+ # close layer with a separate TLS entrance. Never call this same-mode.
+ baseline = json.loads(json.dumps(config["listeners"][0]))
+ baseline.pop("reality-config")
+ baseline.update(
+ name="vless-ws-close-baseline",
+ port=23003,
+ certificate=str(certificate),
+ **{"private-key": str(private_key)},
+ )
+ config["listeners"].append(baseline)
+ reference.pop("reality-opts")
+ reference.update(port=23003, fingerprint=pin)
+ scope = "ws-standard-tls-baseline"
+ elif mode.endswith("-reality") and reference.get("client-fingerprint") in (
+ None,
+ "",
+ "none",
+ ):
+ reference["client-fingerprint"] = "chrome"
+ elif (
+ reference.get("jls-opts")
+ and reference.get("network") == "grpc"
+ and reference.get("client-fingerprint") in (None, "", "none")
+ ):
+ # Official Mihomo v1.19.31's gRPC ALPN reader does not recognize the
+ # ordinary jls-tls ConnectionState type. uTLS JLS does work. Keep the
+ # VCore node unchanged and label this different-profile close baseline.
+ reference["client-fingerprint"] = "chrome"
+ scope = "jls-grpc-chrome-baseline"
+ elif (
+ reference.get("network") == "grpc"
+ and reference.get("ech-opts", {}).get("enable") is True
+ and reference.get("client-fingerprint") in ("safari", "safari16")
+ ):
+ # Official Mihomo v1.19.31/uTLS rejects Safari ECH before business
+ # data with "malformed outer client hello". Compare the same ECH
+ # listener's transport close using Chrome; the VCore node stays Safari.
+ reference["client-fingerprint"] = "chrome"
+ scope = "ech-safari-chrome-baseline"
+ return reference, scope
+
+
+def run(
+ output: Path,
+ selected=None,
+ *,
+ preflight_only=False,
+ client_fingerprint=None,
+ encryption=None,
+ jls=False,
+ ech=False,
+ supplied=None,
+):
+ if client_fingerprint is not None and client_fingerprint not in CLIENT_FINGERPRINTS:
+ raise ValueError("unsupported named client profile")
+ public_cases = PUBLIC_CASES | (
+ {
+ "FINGERPRINT-ANYTLS": ("M", "anytls", True, "public_legacy_regression"),
+ **{
+ f"FINGERPRINT-VMESS-{network.upper()}-TLS": (
+ "V2",
+ f"vmess-{network}",
+ True,
+ "public_legacy_tcp",
+ )
+ for network in ("http", "h2")
+ },
+ }
+ if client_fingerprint
+ else {}
+ )
+ all_cases = CASES | public_cases
+ if encryption is not None:
+ from .protocol_encryption import cases as encryption_profiles
+ from .protocol_encryption_public import catalog
+
+ if encryption not in encryption_profiles():
+ raise ValueError("unsupported Encryption fixture")
+ all_cases = catalog()
+ public_cases = {
+ key: value
+ for key, value in all_cases.items()
+ if not value[3].startswith("native_")
+ }
+ if jls:
+ from .protocol_jls import catalog
+
+ all_cases = catalog()
+ public_cases = {
+ key: value
+ for key, value in all_cases.items()
+ if not value[3].startswith("native_")
+ }
+ if ech:
+ if jls:
+ raise ValueError("ECH and JLS are mutually exclusive")
+ from .protocol_ech import catalog
+
+ all_cases = catalog()
+ public_cases = {
+ key: value
+ for key, value in all_cases.items()
+ if not value[3].startswith("native_")
+ }
+ selected = list(all_cases) if selected is None else selected
+ if (
+ not selected
+ or len(set(selected)) != len(selected)
+ or not set(selected) <= all_cases.keys()
+ ):
+ raise ValueError("invalid VLESS native selection")
+ if client_fingerprint and any(not all_cases[case][2] for case in selected):
+ raise ValueError("named client profiles require TLS cases")
+ output.mkdir(parents=True, exist_ok=False)
+ if preflight_only:
+ # One listener/origin group per official implementation, not a traffic run.
+ kinds = {all_cases[case][0] for case in selected}
+ selected = [
+ next(case for case in selected if all_cases[case][0] == kind)
+ for kind in sorted(kinds)
+ ]
+ report = dict(
+ stage="SECURITY.ech"
+ if ech
+ else "SECURITY.jls"
+ if jls
+ else "SECURITY.encryption"
+ if encryption
+ else "FINGERPRINT-INTEROP"
+ if client_fingerprint
+ else "VLESS",
+ jls=jls,
+ ech=ech,
+ encryption_profile=encryption,
+ client_fingerprint=client_fingerprint,
+ scope="container-wire-and-public-consumer",
+ source=source_identity(),
+ status="NOT RUN",
+ phase="preflight",
+ cases=[],
+ peers={},
+ isolation={},
+ )
+ try:
+ artifacts = {}
+ for kind in sorted({all_cases[case][0] for case in selected} | {"M"}):
+ directory = output / "binaries" / kind
+ if supplied is not None:
+ artifacts[kind] = PeerArtifact(*supplied[kind])
+ elif kind == "M":
+ identity = {}
+ binary = download_mihomo(
+ "linux-arm64", directory=directory, identity=identity
+ )
+ artifacts[kind] = PeerArtifact(binary, identity)
+ else:
+ artifacts[kind] = download_native(
+ kind, directory, "linux-arm64", defer_version=True
+ )
+ report["peers"][kind] = artifacts[kind].identity
+ lab = ContainerLab(report["isolation"], mtu=1500)
+ report["phase"] = "build"
+ built = run_command(
+ [
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ "vless_native",
+ "--test",
+ "vless_public",
+ "--no-run",
+ ],
+ timeout=180,
+ )
+ (output / "build.log").write_text(redact(built.stdout.decode(errors="replace")))
+ if built.returncode != 0 or not built.cleanup:
+ raise RuntimeError("container wire build failed")
+ # Reuse a peer only within one transport; every case gets fresh origin
+ # controls/ports and sessions. One downloaded release snapshot per run.
+ groups = {}
+ for case in selected:
+ kind, mode, encrypted, test = all_cases[case]
+ groups.setdefault((kind, mode, encrypted), []).append((case, test))
+ for (kind, mode, encrypted), cases in groups.items():
+ report["phase"] = "peer-start"
+ with tempfile.TemporaryDirectory(
+ prefix="private-", dir=output
+ ) as temporary:
+ root = Path(temporary)
+ with contextlib.ExitStack() as stack:
+ origin_dir, server_dir = root / "origin", root / "server"
+ origin_dir.mkdir()
+ server_dir.mkdir()
+ shutil.copyfile(
+ Path(__file__).with_name("container_udp_origin.py"),
+ origin_dir / "origin.py",
+ )
+ shutil.copyfile(
+ Path(__file__).with_name("container_close_client.py"),
+ origin_dir / "close.py",
+ )
+ shutil.copyfile(
+ Path(__file__).with_name("container_tls_bio.py"),
+ origin_dir / "tls_bio.py",
+ )
+ artifact = artifacts[kind]
+ shutil.copy2(artifact.binary, server_dir / "peer")
+ tag = f"{mode}-{'tls' if encrypted else 'plain'}"
+ origin_cert, origin_key, origin_pin = certificates(origin_dir)
+ origin = lab.start(
+ stack,
+ origin_dir,
+ tag + "-origin",
+ [
+ "env",
+ "VCORE_ISOLATED_ORIGIN=1",
+ f"VCORE_ORIGIN_CERT=/data/fixture/{origin_cert.name}",
+ f"VCORE_ORIGIN_KEY=/data/fixture/{origin_key.name}",
+ "python",
+ "-B",
+ "/data/fixture/origin.py",
+ ],
+ )
+ argv = (
+ [
+ "/data/fixture/peer",
+ "-d",
+ "/data",
+ "-f",
+ "/data/fixture/config.json",
+ ]
+ if kind == "M"
+ else [
+ "/data/fixture/peer",
+ "run",
+ "-c",
+ "/data/fixture/config.json",
+ ]
+ )
+ server = lab.start(stack, server_dir, tag + "-server", argv)
+
+ def retain_logs(origin=origin, server=server, tag=tag):
+ for role, peer in (("origin", origin), ("server", server)):
+ if peer.log.exists():
+ (output / f"{tag}-{role}.log").write_text(
+ redact(
+ # Capture before cleanup: live log
+ # following may buffer short messages.
+ command("logs", peer.name)[-65536:]
+ )
+ )
+
+ stack.callback(retain_logs)
+ version = command(
+ "exec",
+ server.name,
+ "/data/fixture/peer",
+ "-v" if kind == "M" else "version",
+ ).strip()
+ digest = command(
+ "exec", server.name, "sha256sum", "/data/fixture/peer"
+ ).split()[0]
+ if not version or digest != artifact.identity["binary_sha256"]:
+ raise RuntimeError("container peer identity mismatch")
+ artifact.identity["version"] = version
+ # Non-leaf pin still exercises actual certificate name checks.
+ from .protocol_fixtures import certificate_chain
+
+ cert, key, pin = (
+ certificate_chain(server_dir)
+ if encrypted
+ else certificates(server_dir)
+ )
+ identities = {}
+ if mode == "anytls":
+ node = dict(
+ name="peer",
+ type="anytls",
+ server=server.ipv4,
+ port=23000,
+ password="fixture",
+ sni="localhost",
+ udp=True,
+ fingerprint=pin,
+ )
+ config = {
+ "listeners": [
+ {
+ "name": "anytls",
+ "type": "anytls",
+ "listen": "::",
+ "port": 23000,
+ "users": {"fixture": "fixture"},
+ "certificate": f"/data/fixture/{cert.name}",
+ "private-key": f"/data/fixture/{key.name}",
+ }
+ ],
+ "ipv6": True,
+ "log-level": "silent",
+ "hosts": {"vcore-fixture.test": origin.ipv4},
+ "rules": ["MATCH,DIRECT"],
+ }
+ elif mode.startswith(("vmess-", "trojan-")):
+ legacy_mode = mode.removeprefix("vmess-")
+ node = legacy_node(legacy_mode, True, server.ipv4, pin)
+ config = legacy_peer(
+ kind,
+ legacy_mode,
+ True,
+ 23000,
+ Path("/data/fixture") / cert.name,
+ Path("/data/fixture") / key.name,
+ )
+ if kind == "M":
+ config["hosts"] = {"vcore-fixture.test": origin.ipv4}
+ config["listeners"][0]["listen"] = "::"
+ else:
+ config["dns"]["hosts"] = {"vcore-fixture.test": origin.ipv4}
+ config["inbounds"][0]["listen"] = "::"
+ else:
+ node, config = configuration(
+ mode.removesuffix("-h1") if jls or ech else mode,
+ server.ipv4,
+ origin.ipv4,
+ Path("/data/fixture") / cert.name,
+ Path("/data/fixture") / key.name,
+ )
+ node["name"] = "peer"
+ if encrypted and not mode.endswith("-reality"):
+ node["fingerprint"] = pin
+ if mode.endswith("-mtls"):
+ identities = client_identities(server_dir)
+ node.update(identities["valid"])
+ config["listeners"][0].update(
+ {
+ "client-auth-type": "require-and-verify",
+ "client-auth-cert": "/data/fixture/root.pem",
+ }
+ )
+ if client_fingerprint:
+ node["client-fingerprint"] = client_fingerprint
+ extra_fixture = {}
+ if ech:
+ from .protocol_ech import configuration as ech_config
+
+ extra_fixture = ech_config(node, config, server_dir, mode)
+ if jls:
+ from .protocol_jls import configuration as jls_config
+
+ extra_fixture = jls_config(node, config, origin.ipv4, mode)
+ if encryption:
+ from .protocol_encryption_public import (
+ configuration as encrypted_config,
+ )
+
+ encrypted_config(encryption, node, config)
+ if mode == "vision-encryption":
+ node.pop("tls", None)
+ node.pop("servername", None)
+ for listener in config["listeners"]:
+ listener.pop("certificate", None)
+ listener.pop("private-key", None)
+ listener["allow-insecure"] = True
+ reference_node = None
+ reference_scope = None
+ if any(test in CLOSE_TESTS for _, test in cases):
+ reference_node, reference_scope = close_reference(
+ mode,
+ node,
+ config,
+ Path("/data/fixture") / cert.name,
+ Path("/data/fixture") / key.name,
+ pin,
+ )
+ (server_dir / "config.json").write_text(json.dumps(config))
+ upstream = None
+ hop = None
+ if any(case in public_cases for case, _ in cases):
+ upstream_dir = root / "upstream"
+ upstream_dir.mkdir()
+ shutil.copy2(artifacts["M"].binary, upstream_dir / "peer")
+ upstream = lab.start(
+ stack,
+ upstream_dir,
+ tag + "-upstream",
+ [
+ "/data/fixture/peer",
+ "-d",
+ "/data",
+ "-f",
+ "/data/fixture/config.json",
+ ],
+ )
+ (upstream_dir / "config.json").write_text(
+ json.dumps(
+ {
+ "socks-port": 23001,
+ "allow-lan": True,
+ "bind-address": "*",
+ "log-level": "silent",
+ "ipv6": True,
+ "hosts": {"peer.fixture.test": server.ipv4},
+ "rules": ["MATCH,DIRECT"],
+ }
+ )
+ )
+ hop = dict(
+ name="hop",
+ type="socks5",
+ server=upstream.ipv4,
+ port=23001,
+ udp=True,
+ )
+ upstream.release()
+ upstream.wait_tcp(23001)
+ fixture = root / "input.json"
+ fixture.write_text(
+ json.dumps(
+ dict(
+ isolation="containers",
+ origin_control=f"{origin.ipv4}:24000",
+ origin_ipv4=origin.ipv4,
+ origin_ipv6=origin.ipv6,
+ server_ipv6=server.ipv6,
+ data_dir=str(root / "data"),
+ node=node,
+ vision_probe=mode.startswith("vision-"),
+ flow_reject_port=23004
+ if mode.startswith("vision-")
+ else None,
+ origin_pin=origin_pin,
+ origin_root_der=list(
+ ssl.PEM_cert_to_DER_cert(origin_cert.read_text())
+ ),
+ identities=identities,
+ root_der=list(
+ ssl.PEM_cert_to_DER_cert(
+ (
+ server_dir / "root.pem"
+ if encrypted
+ else cert
+ ).read_text()
+ )
+ ),
+ hop=hop,
+ peer_kind=kind,
+ **extra_fixture,
+ )
+ )
+ )
+ origin.release()
+ server.release()
+ origin.wait_tcp(24000)
+ if mode.endswith("-reality") or jls:
+ origin.wait_tcp(24001)
+ server.wait_tcp(23000)
+ comparison = None
+ if reference_node is not None:
+ comparison_dir = root / "comparison"
+ comparison_dir.mkdir()
+ shutil.copy2(artifacts["M"].binary, comparison_dir / "peer")
+ (comparison_dir / "config.json").write_text(
+ json.dumps(
+ {
+ "socks-port": 23002,
+ "allow-lan": True,
+ "bind-address": "*",
+ "log-level": "warning",
+ "ipv6": True,
+ "proxies": [reference_node],
+ "rules": ["MATCH,reference"],
+ }
+ )
+ )
+ comparison = lab.start(
+ stack,
+ comparison_dir,
+ tag + "-comparison",
+ [
+ "/data/fixture/peer",
+ "-d",
+ "/data",
+ "-f",
+ "/data/fixture/config.json",
+ ],
+ )
+ comparison.release()
+ comparison.wait_tcp(23002)
+ stack.callback(
+ lambda peer=comparison, tag=tag: (
+ output / f"{tag}-comparison.log"
+ ).write_text(redact(command("logs", peer.name)[-65536:]))
+ )
+ observed_close = run_command(
+ [
+ "container",
+ "exec",
+ origin.name,
+ "env",
+ "VCORE_ISOLATED_ORIGIN=1",
+ "python",
+ "-B",
+ "/data/fixture/close.py",
+ comparison.ipv4,
+ origin.ipv4,
+ ],
+ timeout=30,
+ )
+ (output / f"{tag}-close-command.log").write_text(
+ redact(observed_close.stdout.decode(errors="replace"))
+ )
+ if observed_close.returncode or not observed_close.cleanup:
+ raise RuntimeError("official close comparison failed")
+ reference = json.loads(observed_close.stdout)
+ reference["scope"] = reference_scope
+ reference["client_fingerprint"] = reference_node.get(
+ "client-fingerprint"
+ )
+ reference["dut_client_fingerprint"] = node.get(
+ "client-fingerprint"
+ )
+ (output / f"{tag}-close-reference.json").write_text(
+ json.dumps(reference) + "\n"
+ )
+ data = json.loads(fixture.read_text())
+ data["close_reference"] = reference
+ if any(
+ test == "native_vision_direct_close_alignment"
+ for _, test in cases
+ ):
+ direct = run_command(
+ [
+ "container",
+ "exec",
+ origin.name,
+ "env",
+ "VCORE_ISOLATED_ORIGIN=1",
+ "python",
+ "-B",
+ "/data/fixture/close.py",
+ comparison.ipv4,
+ origin.ipv4,
+ "vision-direct",
+ ],
+ timeout=30,
+ )
+ (output / f"{tag}-direct-close-command.log").write_text(
+ redact(direct.stdout.decode(errors="replace"))
+ )
+ if direct.returncode or not direct.cleanup:
+ raise RuntimeError(
+ "official direct close comparison failed"
+ )
+ direct_reference = json.loads(direct.stdout)
+ direct_reference["scope"] = reference_scope
+ (output / f"{tag}-direct-close-reference.json").write_text(
+ json.dumps(direct_reference) + "\n"
+ )
+ data["direct_close_reference"] = direct_reference
+ fixture.write_text(json.dumps(data))
+ report["phase"] = "execute"
+ for case, test in cases:
+ if preflight_only:
+ continue
+ print(case, flush=True)
+ record = dict(case_id=case, status="NOT RUN", peer_kind=kind)
+ report["cases"].append(record)
+ events = output / f"{case}-events.jsonl"
+ test_command = [
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ "vless_public" if case in public_cases else "vless_native",
+ test,
+ "--",
+ "--ignored",
+ "--exact",
+ "--nocapture",
+ ]
+ result = run_command(
+ test_command,
+ cwd=CORE_DIR,
+ timeout=240,
+ limit=4 * 1024 * 1024,
+ env=dict(
+ os.environ,
+ VCORE_VLESS_PEER=f"{server.ipv4}:23000",
+ VCORE_VLESS_TRANSPORT=json.dumps(
+ dict(
+ mode=mode,
+ tls=encrypted,
+ pin=pin,
+ peer_kind=kind,
+ udp_path_limit=15000,
+ )
+ ),
+ VCORE_VLESS_ORIGIN_V4=origin.ipv4,
+ VCORE_VLESS_INPUT=str(fixture),
+ VCORE_CASE_EVENTS=str(events),
+ VCORE_PROTOCOL_STAGE="SECURITY"
+ if encryption or jls or ech
+ else "VLESS",
+ ),
+ )
+ (output / f"{case}.log").write_text(
+ redact(result.stdout.decode(errors="replace"))
+ )
+ observed = read_events(events) if events.exists() else []
+ record.update(
+ command=test_command,
+ exit_code=result.returncode,
+ seconds=result.seconds,
+ command_cleanup=result.cleanup,
+ status="PASS"
+ if result.returncode == 0
+ and result.cleanup
+ and (
+ events_pass(
+ observed,
+ test,
+ mode,
+ stage="SECURITY"
+ if encryption or jls or ech
+ else "VLESS",
+ )
+ if case in public_cases
+ else observed
+ == [
+ dict(
+ schema_version=1,
+ suite="SECURITY-WIRE"
+ if encryption or jls or ech
+ else "VLESS-WIRE",
+ assertion=test,
+ status=status,
+ )
+ for status in ("BEGIN", "PASS")
+ ]
+ )
+ else "FAIL",
+ )
+ server.ensure_alive()
+ origin.ensure_alive()
+ print(f"{case}: {record['status']}", flush=True)
+ for case, _ in cases:
+ if preflight_only:
+ continue
+ next(item for item in report["cases"] if item["case_id"] == case)[
+ "cleanup"
+ ] = all(
+ peer.record["joined"]
+ for peer in [server, origin] + ([upstream] if upstream else [])
+ )
+ report["status"] = (
+ "READY"
+ if preflight_only
+ else "PASS"
+ if (preflight_only or len(report["cases"]) == len(selected))
+ and all(case["status"] == "PASS" for case in report["cases"])
+ else "FAIL"
+ )
+ except KeyboardInterrupt:
+ report.update(status="INTERRUPTED", reason="user interruption")
+ except (OSError, RuntimeError, ValueError, KeyError) as error:
+ report.update(
+ status="BLOCKED" if report["phase"] == "preflight" else "FAIL",
+ reason=str(error)
+ if isinstance(error, RuntimeError)
+ else type(error).__name__,
+ )
+ finally:
+ report["cleanup"] = all(
+ peer["joined"] for peer in report["isolation"].get("peers", [])
+ )
+ report["source_unchanged"] = (
+ source_identity()["source_tree_sha256"]
+ == report["source"]["source_tree_sha256"]
+ )
+ if report["status"] in {"PASS", "READY"} and not (
+ report["cleanup"] and report["source_unchanged"]
+ ):
+ report["status"] = "FAIL"
+ (output / "vless-results.json").write_text(json.dumps(report, indent=2) + "\n")
+ return (
+ 0
+ if report["status"] in {"PASS", "READY"}
+ else (130 if report["status"] == "INTERRUPTED" else 1)
+ )
+
+
+if __name__ == "__main__":
+ import sys
+
+ from .mihomo_isolation import exclusive_run
+
+ with exclusive_run():
+ sys.exit(run(Path(sys.argv[1]).resolve(), sys.argv[2:] or None))
diff --git a/scripts/src/vcore_scripts/protocol_vless_peers.py b/scripts/src/vcore_scripts/protocol_vless_peers.py
new file mode 100644
index 0000000..236aee9
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_vless_peers.py
@@ -0,0 +1,219 @@
+"""VLESS isolated native fixtures. No host service or reference checkout is used."""
+
+from pathlib import Path
+
+MODES = [
+ mode + suffix
+ for mode in (
+ "tcp",
+ "ws",
+ "ws-ed-1",
+ "ws-ed-2048",
+ "upgrade",
+ "upgrade-fast",
+ "grpc",
+ "http",
+ "h2",
+ "ws-header",
+ "ws-path",
+ )
+ for suffix in ("", "-tls")
+] + [
+ "xhttp-stream-one",
+ "xhttp-stream-up",
+ "xhttp-packet-up",
+ "vision-tls",
+ "vision-reality",
+ "tcp-reality",
+ "ws-reality",
+ "grpc-reality",
+ "upgrade-reality",
+ "upgrade-fast-reality",
+ "tcp-mtls",
+ "ws-mtls",
+ "grpc-mtls",
+ "xhttp-stream-one-reality",
+ "xhttp-stream-up-reality",
+ "xhttp-packet-up-reality",
+ "xhttp-stream-up-download",
+ "xhttp-packet-up-download",
+ "xhttp-stream-up-download-reality",
+ "xhttp-packet-up-download-reality",
+ "grpc-path-tls",
+]
+
+
+def peer_kind(mode):
+ base = mode.removesuffix("-tls").removesuffix("-reality").removesuffix("-mtls")
+ return "V2" if base in {"http", "h2", "ws-header", "ws-path"} else "M"
+
+
+def configuration(mode, server, origin, cert: Path, key: Path):
+ encrypted = mode.endswith(("-tls", "-reality", "-mtls")) or mode.startswith(
+ ("xhttp-", "vision-")
+ )
+ base = mode.removesuffix("-tls").removesuffix("-reality").removesuffix("-mtls")
+ separate_download = base.endswith("-download")
+ base = base.removesuffix("-download")
+ kind = peer_kind(mode)
+ identity = "07070707-0707-0707-0707-070707070707"
+ node = dict(
+ name="edge", type="vless", server=server, port=23000, uuid=identity, udp=True
+ )
+ if encrypted:
+ node.update(tls=True, servername="localhost")
+ if base.startswith("xhttp-"):
+ node.update(
+ network="xhttp",
+ **{
+ "xhttp-opts": dict(
+ path="/vless", host="localhost", mode=base.removeprefix("xhttp-")
+ )
+ },
+ )
+ if separate_download:
+ node["xhttp-opts"]["download-settings"] = {}
+ elif base.startswith(("ws", "upgrade")):
+ ws = dict(path="/vless-ws", headers={"Host": "localhost"})
+ if base in {"ws-header", "ws-path"}:
+ ws.update(
+ path="/vless-ws/",
+ **{
+ "max-early-data": 2048,
+ "early-data-header-name": "X-Vcore-Ed"
+ if base == "ws-header"
+ else "",
+ },
+ )
+ elif base in {"ws-ed-1", "ws-ed-2048"}:
+ ws["max-early-data"] = int(base.removeprefix("ws-ed-"))
+ elif base.startswith("upgrade"):
+ ws.update(
+ **{
+ "v2ray-http-upgrade": True,
+ "v2ray-http-upgrade-fast-open": base == "upgrade-fast",
+ "max-early-data": 1,
+ }
+ )
+ node.update(network="ws", **{"ws-opts": ws})
+ elif base in {"grpc", "grpc-path"}:
+ node.update(
+ network="grpc",
+ **{
+ "grpc-opts": dict(
+ **{
+ "grpc-service-name": "/vless-grpc/Tun"
+ if base == "grpc-path"
+ else "vless-grpc",
+ "grpc-user-agent": "VCore-VLESS",
+ "ping-interval": 1,
+ }
+ )
+ },
+ )
+ elif base == "http":
+ node.update(
+ network="http",
+ **{
+ "http-opts": dict(
+ method="POST", path=["/vless-http"], headers={"Host": ["localhost"]}
+ )
+ },
+ )
+ elif base == "h2":
+ node.update(
+ network="h2", **{"h2-opts": dict(host=["localhost"], path="/vless-h2")}
+ )
+ if kind == "M":
+ listener = dict(
+ name="vless",
+ type="vless",
+ listen="::",
+ port=23000,
+ users=[dict(username="fixture", uuid=identity)],
+ )
+ if mode.startswith("vision-"):
+ listener["users"][0]["flow"] = "xtls-rprx-vision"
+ node["flow"] = "xtls-rprx-vision"
+ if encrypted:
+ listener.update(certificate=str(cert), **{"private-key": str(key)})
+ else:
+ listener["allow-insecure"] = True
+ if mode.endswith("-reality"):
+ from .mihomo_extended import PRIVATE_KEY, PUBLIC_KEY, SHORT_ID
+
+ listener.pop("certificate", None)
+ listener.pop("private-key", None)
+ listener["reality-config"] = {
+ "dest": f"{origin}:24001",
+ "private-key": PRIVATE_KEY,
+ "short-id": [SHORT_ID],
+ "server-names": ["localhost"],
+ }
+ node["reality-opts"] = {"public-key": PUBLIC_KEY, "short-id": SHORT_ID}
+ if node.get("network") == "ws":
+ listener["ws-path"] = "/vless-ws"
+ if base in {"grpc", "grpc-path"}:
+ listener["grpc-service-name"] = "vless-grpc"
+ if base == "ws-alpn":
+ node["alpn"] = ["h2", "http/1.1"]
+ listener["grpc-service-name"] = "vless-alpn"
+ if base.startswith("xhttp-"):
+ listener["xhttp-config"] = dict(path="/vless", mode="auto")
+ listeners = [listener]
+ if mode.startswith("vision-"):
+ # Mihomo permits an explicit empty flow even for a Vision user.
+ # Rejection requires a Vision request against an ordinary user.
+ listeners.append(
+ dict(
+ listener,
+ name="vless-flow-rejection",
+ port=23004,
+ users=[dict(user, flow="") for user in listener["users"]],
+ )
+ )
+ return node, dict(
+ ipv6=True,
+ mode="rule",
+ **{"log-level": "silent"},
+ hosts={"vcore-fixture.test": origin},
+ listeners=listeners,
+ rules=["MATCH,DIRECT"],
+ )
+ stream = dict(network="tcp", security="tls" if encrypted else "none")
+ if base == "http":
+ stream["tcpSettings"] = dict(
+ header=dict(type="http", request=dict(path=["/vless-http"]))
+ )
+ elif base == "h2":
+ stream.update(
+ network="http", httpSettings=dict(host=["localhost"], path="/vless-h2")
+ )
+ else:
+ stream.update(
+ network="ws",
+ wsSettings=dict(
+ path="/vless-ws/",
+ maxEarlyData=2048,
+ earlyDataHeaderName="X-Vcore-Ed" if base == "ws-header" else "",
+ ),
+ )
+ if encrypted:
+ stream["tlsSettings"] = dict(
+ alpn=["h2"] if base == "h2" else ["http/1.1"],
+ certificates=[dict(certificateFile=str(cert), keyFile=str(key))],
+ )
+ return node, dict(
+ log={"loglevel": "none"},
+ dns={"hosts": {"vcore-fixture.test": origin}},
+ inbounds=[
+ dict(
+ listen="::",
+ port=23000,
+ protocol="vless",
+ settings=dict(clients=[dict(id=identity)], decryption="none"),
+ streamSettings=stream,
+ )
+ ],
+ outbounds=[dict(protocol="freedom", settings={"domainStrategy": "UseIP"})],
+ )
diff --git a/scripts/src/vcore_scripts/protocol_vless_public.py b/scripts/src/vcore_scripts/protocol_vless_public.py
new file mode 100644
index 0000000..6ee59ee
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_vless_public.py
@@ -0,0 +1,154 @@
+"""Frozen VLESS native/public consumer requirements; no result-derived catalog."""
+
+from .protocol_evidence import idle_resources
+from .protocol_vless_peers import MODES, peer_kind
+from .protocol_vmess_public import pairs
+
+PUBLIC = {}
+WIRE = {}
+
+
+def add(mode, suffix, test, *, wire=False):
+ kind = peer_kind(mode)
+ encrypted = mode.endswith(("-tls", "-reality", "-mtls")) or mode.startswith(
+ ("xhttp-", "vision-")
+ )
+ (WIRE if wire else PUBLIC)[f"VLESS-{mode.upper()}-{suffix}"] = (
+ kind,
+ mode,
+ encrypted,
+ test,
+ )
+
+
+for mode in MODES:
+ add(mode, "BASE", "public_base")
+add("ws-alpn-tls", "NEG", "public_alpn_rejection")
+for mode in ("tcp", "ws", "grpc", "http", "h2"):
+ for suffix in ("", "-tls"):
+ add(mode + suffix, "NEG", "public_negative")
+ for suffix, test in (
+ ("GRAPH", "runtime::public_graph"),
+ ("IPV6", "runtime::public_ipv6_and_gates"),
+ ("ENTRYPOINTS", "runtime::public_entrypoints"),
+ ):
+ add(mode + "-tls", suffix, test)
+for mode in (
+ "upgrade-tls",
+ "upgrade-fast-tls",
+ "upgrade-reality",
+ "upgrade-fast-reality",
+ "tcp-reality",
+ "ws-reality",
+ "grpc-reality",
+ "vision-tls",
+ "vision-reality",
+ "xhttp-stream-one",
+ "xhttp-stream-up",
+ "xhttp-packet-up",
+):
+ add(mode, "NEG", "public_negative")
+for mode in ("tcp-tls", "grpc-tls", "vision-tls", "vision-reality"):
+ add(mode, "LIFE", "runtime::public_lifecycle")
+ add(mode, "OWNED", "runtime::owned_resources")
+for mode in ("tcp-tls", "grpc-tls", "vision-tls"):
+ add(mode, "UDP-ISOLATION", "runtime::public_udp_isolation")
+for mode in ("vision-tls", "vision-reality"):
+ add(mode, "INNER-TLS", "native_vision_inner_tls", wire=True)
+ add(mode, "GRAPH", "runtime::public_graph")
+ add(mode, "ENTRYPOINTS", "runtime::public_entrypoints")
+ add(mode, "IPV6", "runtime::public_ipv6_and_gates")
+for mode in ("tcp", "grpc-tls", "http", "h2-tls"):
+ add(mode, "UDP-BOUNDARIES", "native_three_udp_encodings", wire=True)
+for mode in ("tcp-mtls", "ws-mtls", "grpc-mtls"):
+ add(mode, "IDENTITY", "public_tls_identity_and_verification_name")
+add(
+ "grpc-tls",
+ "POOL-SELECTION",
+ "runtime::grpc_pool_keeps_physical_selection_until_new_transport",
+)
+for protocol in ("vmess", "trojan"):
+ for network in ("tcp", "ws", "grpc"):
+ PUBLIC[f"VLESS-REGRESSION-{protocol.upper()}-{network.upper()}"] = (
+ "M",
+ f"{protocol}-{network}",
+ True,
+ "public_legacy_regression",
+ )
+for mode in (
+ "tcp",
+ "tcp-tls",
+ "tcp-reality",
+ "ws-reality",
+ "grpc-reality",
+ "ws",
+ "ws-tls",
+ "grpc",
+ "grpc-tls",
+ "http",
+ "http-tls",
+ "h2",
+ "h2-tls",
+ "upgrade-fast-tls",
+ "upgrade-reality",
+ "upgrade-fast-reality",
+ "vision-tls",
+ "vision-reality",
+ "xhttp-stream-one",
+ "xhttp-stream-up",
+ "xhttp-packet-up",
+):
+ add(
+ mode,
+ "CLOSE",
+ "native_ws_reality_close_boundary"
+ if mode in {"ws-reality", "upgrade-reality", "upgrade-fast-reality"}
+ else "native_mihomo_close_alignment",
+ wire=True,
+ )
+add("grpc-tls", "POOL-COUNTS", "native_grpc_pool_thresholds", wire=True)
+CASES = WIRE | PUBLIC
+
+
+def events_pass(events, test, mode, *, stage="VLESS"):
+ main = [event for event in events if event.get("suite") == f"{stage}-PUBLIC"]
+ if len(main) != 2 or not pairs(main, f"{stage}-PUBLIC", test, 1):
+ return False
+ if any(
+ event.get("schema_version") != 1 or event.get("status") not in {"BEGIN", "PASS"}
+ for event in events
+ ):
+ return False
+ if test == "public_base" and not (
+ pairs(events, f"{stage}-BASE", "tcp_10mib_both_directions", 3)
+ and pairs(
+ events,
+ f"{stage}-BASE",
+ "udp_each_codec_and_family",
+ 1 if mode.startswith("vision-") else 3,
+ )
+ ):
+ return False
+ if test in {"runtime::public_lifecycle", "runtime::owned_resources"}:
+ suite = (
+ f"{stage}-LIFE" if test.endswith("public_lifecycle") else f"{stage}-OWNED"
+ )
+ if not pairs(events, suite, "stop_and_remain_quiet", 20):
+ return False
+ for event in [
+ e for e in events if e.get("suite") == suite and e["status"] == "PASS"
+ ]:
+ if event.get("seconds", 0) < 5:
+ return False
+ if suite == f"{stage}-OWNED":
+ points = event.get("checkpoints", [])
+ phases = {p["phase"]: p["resources"] for p in points}
+ if (
+ len(points) != 3
+ or set(phases) != {"baseline", "after-stop", "quiet"}
+ or not all(idle_resources(r) for r in phases.values())
+ or phases["after-stop"] != phases["quiet"]
+ or not idle_resources(event.get("resources"))
+ ):
+ return False
+ return True
diff --git a/scripts/src/vcore_scripts/protocol_vless_security.py b/scripts/src/vcore_scripts/protocol_vless_security.py
new file mode 100644
index 0000000..acc6bd7
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_vless_security.py
@@ -0,0 +1,94 @@
+"""Ephemeral public-test identities. Keys never leave the private fixture."""
+
+from pathlib import Path
+
+from .protocol_fixtures import certificates
+from .protocol_peers import run_command
+
+
+def client_identities(directory: Path):
+ result = {}
+ extensions = directory / "client-ext.cnf"
+ extensions.write_text(
+ "basicConstraints=critical,CA:FALSE\nkeyUsage=critical,digitalSignature\nextendedKeyUsage=clientAuth\n"
+ )
+ (directory / "index.txt").write_text("")
+ (directory / "serial.txt").write_text("10\n")
+ ca = directory / "client-ca.cnf"
+ ca.write_text(
+ "[ca]\ndefault_ca=fixture\n[fixture]\n"
+ f"database={directory / 'index.txt'}\nserial={directory / 'serial.txt'}\n"
+ f"new_certs_dir={directory}\ncertificate={directory / 'root.pem'}\n"
+ f"private_key={directory / 'root-key.pem'}\n"
+ "default_md=sha256\npolicy=names\n[names]\ncommonName=supplied\n"
+ )
+ for name, days in (("valid", "2"), ("expired", "2")):
+ key, csr, cert = (
+ directory / f"client-{name}.{suffix}" for suffix in ("key", "csr", "pem")
+ )
+ for argv in (
+ [
+ "openssl",
+ "req",
+ "-new",
+ "-newkey",
+ "rsa:2048",
+ "-nodes",
+ "-subj",
+ "/CN=synthetic-client",
+ "-keyout",
+ str(key),
+ "-out",
+ str(csr),
+ ],
+ [
+ "openssl",
+ "x509",
+ "-req",
+ "-in",
+ str(csr),
+ "-CA",
+ str(directory / "root.pem"),
+ "-CAkey",
+ str(directory / "root-key.pem"),
+ "-set_serial",
+ "3" if name == "valid" else "4",
+ "-days",
+ days,
+ "-extfile",
+ str(extensions),
+ "-out",
+ str(cert),
+ ],
+ ):
+ if name == "expired" and argv[1] == "x509":
+ argv = [
+ "openssl",
+ "ca",
+ "-batch",
+ "-notext",
+ "-config",
+ str(ca),
+ "-in",
+ str(csr),
+ "-out",
+ str(cert),
+ "-extfile",
+ str(extensions),
+ "-startdate",
+ "20000101000000Z",
+ "-enddate",
+ "20010101000000Z",
+ ]
+ command = run_command(argv, timeout=20, limit=65536)
+ if command.returncode or not command.cleanup:
+ raise RuntimeError("synthetic client identity generation failed")
+ result[name] = {"certificate": cert.read_text(), "private-key": key.read_text()}
+ wrong = directory / "wrong-ca"
+ wrong.mkdir()
+ cert, key, _ = certificates(wrong)
+ result["wrong-ca"] = {
+ "certificate": cert.read_text(),
+ "private-key": key.read_text(),
+ }
+ return result
diff --git a/scripts/src/vcore_scripts/protocol_vmess.py b/scripts/src/vcore_scripts/protocol_vmess.py
new file mode 100644
index 0000000..8723aea
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_vmess.py
@@ -0,0 +1,132 @@
+"""VMESS wire gate; all peers and origins run in isolated containers."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from .mihomo_isolation import exclusive_run
+
+CASES = {
+ "VMESS-M-IDENTITY": ("M", "tcp", False, "native_identity_time_replay_rejection")
+}
+CASES["VMESS-M-RAW-UDP"] = ("M", "tcp", False, "native_raw_udp_boundaries")
+CASES["VMESS-M-ENCODED-UDP"] = ("M", "tcp", False, "native_encoded_udp_boundaries")
+for _mode in ("tcp", "ws", "grpc", "http", "h2"):
+ for _tls in (False, True):
+ _kind = "V2" if _mode in {"http", "h2"} else "M"
+ CASES[f"VMESS-{_kind}-{_mode.upper()}-{'TLS' if _tls else 'PLAIN'}"] = (
+ _kind,
+ _mode,
+ _tls,
+ "native_cipher_matrix",
+ )
+ CASES[f"VMESS-{_kind}-{_mode.upper()}-{'TLS' if _tls else 'PLAIN'}-CLOSE"] = (
+ _kind,
+ _mode,
+ _tls,
+ "native_mihomo_close_alignment",
+ )
+ if _mode != "tcp" or _tls:
+ for _encoding in ("raw", "encoded"):
+ CASES[
+ f"VMESS-{_kind}-{_mode.upper()}-{'TLS' if _tls else 'PLAIN'}"
+ f"-{_encoding.upper()}-UDP"
+ ] = (
+ _kind,
+ _mode,
+ _tls,
+ f"native_{_encoding}_udp_boundaries",
+ )
+
+
+def udp_path_limit():
+ # Both packet sender and origin are now Linux VM services.
+ return 15000
+
+
+def peer_config(kind, mode, encrypted, port, cert, key):
+ if mode.startswith("trojan-"):
+ config = peer_config(
+ kind, mode.removeprefix("trojan-"), encrypted, port, cert, key
+ )
+ config["listeners"][0].update(
+ type="trojan",
+ users=[dict(username="fixture", password="synthetic-regression-only")],
+ )
+ return config
+ variant = mode
+ mode = mode.split("-")[0]
+ identity = "07070707-0707-0707-0707-070707070707"
+ if kind == "M":
+ listener = dict(
+ name="vmess",
+ type="vmess",
+ listen="127.0.0.1",
+ port=port,
+ users=[dict(username="fixture", uuid=identity, alterId=0)],
+ )
+ if encrypted:
+ listener.update(certificate=str(cert), **{"private-key": str(key)})
+ if mode == "ws":
+ listener["ws-path"] = "/vmess-ws"
+ if mode == "grpc":
+ listener["grpc-service-name"] = "vmess-grpc"
+ if variant == "ws-alpn":
+ listener["grpc-service-name"] = "vmess-alpn"
+ return {
+ "mode": "rule",
+ "log-level": "silent",
+ "ipv6": True,
+ "hosts": {"vcore-fixture.test": "127.0.0.1"},
+ "listeners": [listener],
+ "rules": ["MATCH,DIRECT"],
+ }
+ stream = dict(network="tcp", security="tls" if encrypted else "none")
+ if mode == "http":
+ stream["tcpSettings"] = {
+ "header": {"type": "http", "request": {"path": ["/vmess-http"]}}
+ }
+ elif mode == "h2":
+ stream.update(
+ network="http", httpSettings=dict(host=["localhost"], path="/vmess-h2")
+ )
+ elif mode == "ws":
+ stream.update(
+ network="ws",
+ wsSettings={
+ "path": "/vmess-ws/",
+ "maxEarlyData": 2048,
+ "earlyDataHeaderName": "X-Vcore-Ed" if variant == "ws-header" else "",
+ },
+ )
+ if encrypted:
+ stream["tlsSettings"] = {
+ "alpn": ["h2"] if mode == "h2" else ["http/1.1"],
+ "certificates": [{"certificateFile": str(cert), "keyFile": str(key)}],
+ }
+ return {
+ "log": {"loglevel": "none"},
+ "dns": {"hosts": {"vcore-fixture.test": "127.0.0.1"}},
+ "inbounds": [
+ {
+ "listen": "127.0.0.1",
+ "port": port,
+ "protocol": "vmess",
+ "settings": {"clients": [{"id": identity, "alterId": 0}]},
+ "streamSettings": stream,
+ }
+ ],
+ "outbounds": [{"protocol": "freedom", "settings": {"domainStrategy": "UseIP"}}],
+ }
+
+
+def run(output: Path, selected=None):
+ from .protocol_vmess_container import run as run_container
+
+ return run_container(output, selected)
+
+
+if __name__ == "__main__":
+ with exclusive_run():
+ sys.exit(run(Path(sys.argv[1]).resolve(), sys.argv[2:] or None))
diff --git a/scripts/src/vcore_scripts/protocol_vmess_acceptance.py b/scripts/src/vcore_scripts/protocol_vmess_acceptance.py
new file mode 100644
index 0000000..d3bfdec
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_vmess_acceptance.py
@@ -0,0 +1,691 @@
+"""VMESS container-only execution and independently recomputed stage acceptance."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from .builds import DEFAULT_FEATURES
+from .protocol_evidence import HEX, idle_resources, new_result, read_events, read_json
+from .protocol_inputs import redact
+from .protocol_vmess import CASES as WIRE
+from .protocol_vmess_container import run as native_run
+from .protocol_vmess_public import CASES as PUBLIC
+from .protocol_vmess_public import events_pass
+
+NATIVE = WIRE | PUBLIC
+FIELD_IDS = {
+ *(f"C{i:02}" for i in range(1, 7)),
+ *(f"T{i:02}" for i in range(2, 6)),
+ *(f"W{i:02}" for i in range(1, 6)),
+ "G01",
+ *(f"H{i:02}" for i in range(1, 7)),
+ *(f"VM{i:02}" for i in range(1, 9)),
+}
+GATES = {
+ "VMESS-CFG",
+ "VMESS-CODEC",
+ "VMESS-CANCEL",
+ "VMESS-REGRESSION",
+ "VMESS-RELEASE",
+ "VMESS-FEATURES",
+ "VMESS-SCRIPTS",
+ "VMESS-QUALITY",
+}
+SCRIPT_ASSERTIONS = [
+ "offline-success",
+ "missing-duplicate-unknown-case",
+ "download-failure",
+ "timeout",
+ "sigint",
+ "partial-start",
+ "permission",
+ "peer-exit",
+ "cleanup-failure",
+ "redaction",
+]
+REQUIRED_IDS = set(NATIVE) | GATES
+# Frozen names, not a regex over test output and not read from the manifest.
+OBSERVATIONS = {
+ "VMESS-CFG": [
+ "vmess_default_node_and_explicit_cipher_aliases_are_accepted_without_io",
+ "vmess_transport_and_security_combinations_are_strict",
+ "vmess_field_boundaries_and_normalized_transport_values",
+ "vmess_normalized_websocket_fields_preserve_headers_and_early_data_order",
+ ],
+ "VMESS-CODEC": [
+ "xudp_cancelled_send_and_bad_frame_release_io_and_cannot_resume",
+ "xudp_zero_global_id_omits_the_optional_extension_like_mihomo",
+ "packetaddr_has_ip_only_address_first_wire_and_rejects_truncation",
+ "vmess_aead_requests_are_fresh_bounded_and_redacted",
+ "vmess_response_authentication_cannot_be_skipped_by_none_cipher",
+ "vmess_whole_close_wakes_reader_and_releases_io_before_response",
+ "xudp_explicit_budget_rejects_max_plus_one_before_writing",
+ "independently_published_nested_hmac_vectors",
+ "chunks_preserve_boundaries_masks_padding_and_authenticated_eof",
+ "tags_lengths_and_nonce_exhaustion_fail_closed",
+ "auto_uses_detected_hardware_not_architecture_name",
+ ],
+ "VMESS-CANCEL": [
+ "vmess_all_handshakes_keep_the_original_deadline_and_join_cancelled_io",
+ "vmess_expired_deadline_and_protect_failure_never_fall_back",
+ ],
+ "VMESS-REGRESSION": [
+ "shared_xudp_receives_frames_without_a_vless_response_header",
+ "first_frame_matches_xray_mux_wire_format",
+ "followup_frame_carries_each_datagrams_destination",
+ "destination_codec_round_trips_all_address_families",
+ "normal_and_error_end_frames_are_distinguishable",
+ "oversized_response_is_rejected_before_payload_read",
+ "fragmented_receive_survives_cancellation_and_resumes",
+ "keepalive_data_is_consumed_without_becoming_an_udp_response",
+ "full_wire_payload_remains_available_to_proxy_inbounds",
+ "request_matches_the_official_sha224_and_socks_address_wire_format",
+ "authentication_and_requests_are_strict_and_never_debug_credentials",
+ "invalid_truncated_and_oversized_frames_fail_closed_without_payload_leaks",
+ "datagram_limits_preserve_messages_and_drain_over_budget_responses",
+ "datagram_sends_one_frame_and_receives_fragmented_consecutive_frames",
+ "cancelled_receive_preserves_partial_frames_and_does_not_block_send",
+ "cancelled_partial_send_poison_closes_without_replaying_or_waiting",
+ "trojan_tcp_configuration_and_node_graph_accept_the_approved_fields",
+ "trojan_tcp_defaults_preserve_credentials_and_address_policy",
+ "trojan_invalid_configuration_is_rejected_without_exposing_credentials",
+ "trojan_ws_and_grpc_configuration_applies_transport_specific_defaults",
+ "trojan_transport_boundaries_fail_before_runtime_io",
+ "transport_options_reject_ambiguous_headers_before_io",
+ "http_first_header_preserves_prefix_raw_continuation_and_half_close_tail",
+ "legacy_h2_keeps_unframed_bytes_server_first_and_owned_whole_close",
+ "websocket_rejects_invalid_upgrade_responses_and_bounded_header_overflows",
+ "websocket_early_data_and_remaining_frames_keep_the_original_byte_order",
+ "setup_deadline_releases_supplied_io_in_stream_adapters",
+ "cancelled_setup_releases_supplied_io_without_a_detached_task",
+ "ws_rejects_oversized_and_truncated_frames_instead_of_reporting_eof",
+ "ws_accepts_mihomo_clean_underlay_eof_only_at_complete_message_boundaries",
+ "dropping_an_established_ws_releases_its_only_io_owner",
+ "grpc_rejects_oversized_truncated_and_invalid_records",
+ "grpc_large_writes_obey_small_http2_windows_and_keep_byte_integrity",
+ "ws_partial_writes_empty_frames_ping_and_half_close_preserve_every_byte",
+ "grpc_handles_response_after_upload_fragmented_records_and_owned_stop",
+ "websocket_supplied_io_preserves_server_first_and_partial_writes",
+ "xhttp_keeps_complete_response_when_peer_resets_after_end_stream",
+ "xhttp_does_not_hide_reset_before_end_stream",
+ "feature_skeletons_do_not_open_unimplemented_yaml_or_measurement_protocols",
+ "future_fields_and_over_limit_documents_remain_rejected",
+ "registry_matches_live_production_constants_and_has_owned_boundary_cases",
+ "webpki_rejects_untrusted_wrong_name_and_expired_unless_explicitly_skipped",
+ "leaf_pin_is_trust_but_nonleaf_pin_checks_chain_name_and_expiry",
+ "ticket_storage_obeys_exact_node_budget_and_consumes_each_ticket_once",
+ "every_certificate_policy_verifies_tls12_and_tls13_handshake_signatures",
+ "vless_keeps_webpki_tls13_and_required_h2_after_anytls_connections",
+ "alpn_and_tls_resumption_are_isolated_between_node_policies",
+ "explicit_verification_name_does_not_change_sni_or_allow_skip_to_override_it",
+ "mutual_tls_identity_is_required_verified_and_not_shared_between_clients",
+ "tls_options_reject_invalid_alpn_identity_and_budget_before_using_a_stream",
+ "certificate_rejection_delivers_no_business_bytes_and_diagnostics_are_redacted",
+ "tls_close_write_sends_notify_without_closing_the_supplied_transport",
+ "tls_close_notify_flush_has_a_five_second_bound",
+ "cancelling_tls_handshake_releases_the_caller_supplied_stream",
+ ],
+ "VMESS-RELEASE": [
+ "vmess_default_node_and_explicit_cipher_aliases_are_accepted_without_io",
+ "vmess_transport_and_security_combinations_are_strict",
+ "vmess_field_boundaries_and_normalized_transport_values",
+ "vmess_normalized_websocket_fields_preserve_headers_and_early_data_order",
+ "xudp_cancelled_send_and_bad_frame_release_io_and_cannot_resume",
+ "xudp_zero_global_id_omits_the_optional_extension_like_mihomo",
+ "packetaddr_has_ip_only_address_first_wire_and_rejects_truncation",
+ "vmess_aead_requests_are_fresh_bounded_and_redacted",
+ "vmess_response_authentication_cannot_be_skipped_by_none_cipher",
+ "vmess_whole_close_wakes_reader_and_releases_io_before_response",
+ "xudp_explicit_budget_rejects_max_plus_one_before_writing",
+ "independently_published_nested_hmac_vectors",
+ "chunks_preserve_boundaries_masks_padding_and_authenticated_eof",
+ "tags_lengths_and_nonce_exhaustion_fail_closed",
+ "auto_uses_detected_hardware_not_architecture_name",
+ "vmess_all_handshakes_keep_the_original_deadline_and_join_cancelled_io",
+ "vmess_expired_deadline_and_protect_failure_never_fall_back",
+ ],
+}
+
+
+def rows(identifier):
+ if identifier == "VMESS-CFG":
+ return sorted(FIELD_IDS)
+ if identifier == "VMESS-CODEC":
+ return ["VM01", "VM03", "VM06", "VM07", "VM08"]
+ if identifier in GATES or identifier.startswith("VMESS-REGRESSION"):
+ return []
+ _, mode, tls, test = NATIVE[identifier]
+ result = {"VM04", "VM05"}
+ if identifier in WIRE:
+ if test == "native_identity_time_replay_rejection":
+ result |= {"VM01", "VM02"}
+ elif test == "native_cipher_matrix":
+ result |= {"VM03", "VM07", "VM08"}
+ elif test.endswith("udp_boundaries"):
+ result.add("VM06")
+ else:
+ result |= {"C01", "C02", "C03", "C04", "VM01", "VM02"}
+ if test == "public_body_options":
+ result |= {"VM03", "VM07", "VM08"}
+ if "graph" in test:
+ result.add("C06")
+ if "base" in test or "udp" in test or "gates" in test:
+ result |= {"C05", "VM06"}
+ if tls:
+ result |= {"T02", "T03", "T05"}
+ if test == "public_negative":
+ result.add("T04")
+ if mode.startswith("ws"):
+ result |= {"W01", "W02", "W03"}
+ if mode != "ws":
+ result |= {"W04", "W05"}
+ if mode.startswith("grpc"):
+ result.add("G01")
+ if mode == "http":
+ result |= {"H01", "H02", "H03", "H04"}
+ if mode == "h2":
+ result |= {"H05", "H06"}
+ return sorted(result)
+
+
+def definitions():
+ cases = []
+ for identifier in sorted(REQUIRED_IDS):
+ kind, mode, tls, test = NATIVE.get(
+ identifier, ("unit", "memory-or-build", False, identifier)
+ )
+ native = identifier in NATIVE
+ substage = "VMESS.acceptance"
+ if identifier in WIRE:
+ substage = (
+ "VMESS.identity"
+ if "identity" in test
+ else "VMESS.codec"
+ if "cipher" in test
+ else "VMESS.udp"
+ if "udp" in test
+ else "VMESS.close"
+ )
+ elif identifier == "VMESS-CODEC":
+ substage = "VMESS.codec"
+ cases.append(
+ dict(
+ case_id=identifier,
+ stage="VMESS",
+ substage=substage,
+ required=True,
+ row_ids=rows(identifier),
+ protocol="vmess",
+ network=mode,
+ security="tls" if tls else "plain",
+ udp_codec="raw/xudp/packetaddr"
+ if "udp" in test or test == "public_base"
+ else "per-assertion",
+ field_values={
+ "network": mode,
+ "tls": tls,
+ "scope": "protocol-consumer",
+ },
+ outer_family="IPv4/IPv6" if "ipv6" in test else "IPv4",
+ inner_family="IPv4/IPv6/domain"
+ if "base" in test or "udp_boundaries" in test
+ else "per-assertion",
+ target_type="isolated synthetic origin" if native else "memory-only",
+ upstream_graph="direct/concrete/nested-select"
+ if "graph" in test
+ else "per-assertion",
+ peer_kind=kind,
+ peer_config=dict(mode=mode, tls=tls, test=test),
+ gap_source={
+ "reason": "Mihomo VMess listener has no HTTP header/legacy H2 "
+ "or custom ED field; official V2Ray supplements only these paths",
+ "source": "https://github.com/MetaCubeX/mihomo/blob/v1.19.31/listener/inbound/vmess.go",
+ }
+ if kind == "V2"
+ else None,
+ expected_observation=[test]
+ if native
+ else SCRIPT_ASSERTIONS
+ if identifier == "VMESS-SCRIPTS"
+ else OBSERVATIONS.get(identifier, [identifier]),
+ required_evidence=["structured-assertions", "command", "cleanup"]
+ + (["peer-identity", "isolated-origins"] if native else []),
+ prerequisites=[
+ "owned-host-only-container-network",
+ "official-latest-peer",
+ ]
+ if native
+ else ["rust-toolchain"],
+ runner="native-vmess" if native else "vmess-gate",
+ timeout_seconds=240 if native else 1200,
+ )
+ )
+ return cases
+
+
+def commands(identifier):
+ cargo = ["cargo", "test", "--locked", "--all-features"]
+ if identifier == "VMESS-CFG":
+ return [cargo + ["--test", "vmess_config"], cargo + ["--lib", "config::"]]
+ if identifier == "VMESS-CODEC":
+ return [cargo + ["--test", "vmess_codec"], cargo + ["--lib", "outbound::vmess"]]
+ if identifier == "VMESS-CANCEL":
+ return [cargo + ["--test", "vmess_lifecycle"]]
+ if identifier == "VMESS-RELEASE":
+ return [
+ cargo
+ + [
+ "--release",
+ "--test",
+ "vmess_config",
+ "--test",
+ "vmess_codec",
+ "--test",
+ "vmess_lifecycle",
+ ],
+ cargo + ["--release", "--lib", "outbound::vmess"],
+ ]
+ if identifier == "VMESS-REGRESSION":
+ return [
+ cargo + ["--lib", "xudp::"],
+ cargo + ["--lib", "security::tls::tests::"],
+ cargo
+ + [
+ "--test",
+ "trojan",
+ "--test",
+ "trojan_config",
+ "--test",
+ "stream_foundations",
+ "--test",
+ "h2_stream_regression",
+ "--test",
+ "feature_foundations",
+ "--test",
+ "limit_foundations",
+ ],
+ cargo
+ + [
+ "--lib",
+ "inbound::listen::tests::socks_udp_send_buffer_covers_the_declared_wire_limit",
+ "--",
+ "--exact",
+ ],
+ ]
+ if identifier == "VMESS-QUALITY":
+ return [
+ ["cargo", "fmt", "--all", "--", "--check"],
+ [
+ "cargo",
+ "clippy",
+ "--locked",
+ "--all-features",
+ "--lib",
+ "--bins",
+ "--",
+ "-D",
+ "warnings",
+ ],
+ ["vcore-scripts", "check", "c-header"],
+ ["vcore-scripts", "check", "tls-dependencies"],
+ ["ruff", "check", "scripts"],
+ ["ruff", "format", "--check", "scripts"],
+ ["git", "diff", "--check"],
+ ["vcore-scripts", "build", "apple"],
+ ["vcore-scripts", "build", "android"],
+ ]
+ return []
+
+
+def gate_result(case, records, events):
+ result = new_result(case)
+ good = bool(records) and all(
+ r.get("exit_code") == 0 and r.get("cleanup") is True for r in records
+ )
+ identifier = case["case_id"]
+ assertions = {}
+ if identifier in OBSERVATIONS:
+ for name in case["expected_observation"]:
+ observed = [e for e in events if e.get("assertion") == name]
+ assertions[name] = len(observed) == 2 and [
+ e.get("status") for e in observed
+ ] == ["BEGIN", "PASS"]
+ good &= (
+ bool(assertions)
+ and all(assertions.values())
+ and all(
+ e.get("schema_version") == 1 and e.get("status") in {"BEGIN", "PASS"}
+ for e in events
+ )
+ )
+ else:
+ assertions = dict.fromkeys(case["expected_observation"], good)
+ result.update(
+ status="PASS" if good else "FAIL",
+ assertions=assertions,
+ evidence=case["required_evidence"] if good else [],
+ command_exit_code=0 if good else 1,
+ cleanup=all(r.get("cleanup") is True for r in records),
+ )
+ return result
+
+
+def native_results(cases, report, directory):
+ records = report.get("cases", [])
+ expected = {case["case_id"] for case in cases}
+ if len(records) != len(expected) or {r.get("case_id") for r in records} != expected:
+ raise ValueError("missing, duplicate or unknown VMess native case")
+ by_id = {record["case_id"]: record for record in records}
+ output = []
+ for case in cases:
+ record = by_id[case["case_id"]]
+ path = directory / (case["case_id"] + "-events.jsonl")
+ observed = read_events(path) if path.exists() else []
+ test = NATIVE[case["case_id"]][3]
+ observed_ok = (
+ events_pass(observed, test)
+ if case["case_id"] in PUBLIC
+ else observed
+ == [
+ dict(
+ schema_version=1, suite="VMESS-WIRE", assertion=test, status=status
+ )
+ for status in ("BEGIN", "PASS")
+ ]
+ )
+ clean = (
+ record.get("command_cleanup") is True
+ and record.get("cleanup") is True
+ and report.get("cleanup") is True
+ )
+ expected_command = [
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ "vmess_public" if case["case_id"] in PUBLIC else "vmess_native",
+ test,
+ "--",
+ "--ignored",
+ "--exact",
+ "--nocapture",
+ ]
+ good = (
+ observed_ok
+ and clean
+ and report.get("source_unchanged") is True
+ and record.get("exit_code") == 0
+ and record.get("status") == "PASS"
+ and record.get("command") == expected_command
+ and record.get("peer_kind") == case["peer_kind"]
+ )
+ result = new_result(case)
+ result.update(
+ status="PASS" if good else "FAIL",
+ assertions={test: observed_ok},
+ evidence=case["required_evidence"] if good else [],
+ command_exit_code=record.get("exit_code"),
+ cleanup=clean,
+ )
+ output.append(result)
+ return output
+
+
+def fields_report(cases, results):
+ statuses = {result["case_id"]: result["status"] for result in results}
+ complete = set(statuses) == REQUIRED_IDS and all(
+ value == "PASS" for value in statuses.values()
+ )
+ fields = []
+ for row in sorted(FIELD_IDS):
+ owners = [c["case_id"] for c in cases if row in c["row_ids"]]
+ fields.append(
+ dict(
+ row_id=row,
+ required_cases=owners,
+ status="PASS" if complete and len(owners) > 1 else "NOT RUN",
+ )
+ )
+ return dict(schema_version=1, stage="VMESS", protocol="vmess", fields=fields)
+
+
+def execute(cases, run, output, results):
+ from .protocol_harness import _command, _features, _scripts
+
+ for case in cases:
+ identifier = case["case_id"]
+ if identifier in NATIVE:
+ continue
+ if identifier == "VMESS-FEATURES":
+ result = _features(case, run, output)
+ build = _command(
+ run,
+ output,
+ "production-build",
+ [
+ "cargo",
+ "build",
+ "--locked",
+ "--release",
+ "--no-default-features",
+ "--features",
+ DEFAULT_FEATURES,
+ "--lib",
+ ],
+ 1200,
+ )
+ if build.returncode or not build.cleanup:
+ result.update(
+ status="FAIL",
+ command_exit_code=build.returncode,
+ cleanup=build.cleanup,
+ )
+ results[identifier] = result
+ elif identifier == "VMESS-SCRIPTS":
+ results[identifier] = _scripts(case, run, output)
+ else:
+ events = []
+ start = len(run["commands"])
+ for index, argv in enumerate(commands(identifier)):
+ path = output / f"{identifier}-{index}-events.jsonl"
+ _command(run, output, f"{identifier}-{index}", argv, 1200, events=path)
+ if path.exists():
+ events.extend(read_events(path))
+ results[identifier] = gate_result(case, run["commands"][start:], events)
+ native = [case for case in cases if case["case_id"] in NATIVE]
+ if native:
+ directory = output / "native"
+ native_run(directory, [case["case_id"] for case in native])
+ report = read_json(directory / "vmess-results.json")
+ (output / "peers.json").write_text(json.dumps(report["peers"], indent=2) + "\n")
+ for result in native_results(native, report, directory):
+ results[result["case_id"]] = result
+ (output / "fields.json").write_text(
+ json.dumps(fields_report(cases, list(results.values())), indent=2) + "\n"
+ )
+
+
+def check(run_dir, cases, run, results, peers, paths):
+ from .protocol_harness import SCRIPT_OBSERVATIONS
+
+ needed = {
+ "native/vmess-results.json",
+ "fields.json",
+ "script-tests.json",
+ "resources.jsonl",
+ "peers.json",
+ "cases.json",
+ "summary.md",
+ }
+ if not needed <= set(paths):
+ raise ValueError("missing VMESS acceptance artifacts")
+ expected = {c["case_id"]: c for c in definitions()}
+ if len(cases) != len(expected) or any(
+ c != expected.get(c["case_id"]) for c in cases
+ ):
+ raise ValueError("VMess frozen case metadata changed")
+ report = read_json(run_dir / "native/vmess-results.json")
+ source_keys = (
+ "parent_commit",
+ "source_tree_sha256",
+ "dirty_patch_sha256",
+ "lock_sha256",
+ )
+ if (
+ report.get("source") != {key: run.get(key) for key in source_keys}
+ or report.get("status") != "PASS"
+ ):
+ raise ValueError("VMess peer evidence input mismatch")
+ isolation = report.get("isolation", {})
+ if (
+ isolation.get("host_servers") is not False
+ or isolation.get("network_mode") != "hostOnly"
+ or not isolation.get("peers")
+ or not all(
+ p.get("joined") is True and p.get("started") is True
+ for p in isolation["peers"]
+ )
+ ):
+ raise ValueError("VMess peers not isolated or cleaned")
+ if peers != report.get("peers") or set(peers) != {"M", "V2"}:
+ raise ValueError("missing VMess official peers")
+ for kind, peer in peers.items():
+ project = "MetaCubeX/mihomo" if kind == "M" else "v2fly/v2ray-core"
+ if (
+ peer.get("kind") != kind
+ or peer.get("target") != "linux-arm64"
+ or not peer.get("version")
+ or not peer.get("source_url", "").startswith(
+ f"https://github.com/{project}/releases/"
+ )
+ or not all(
+ HEX.fullmatch(peer.get(key, ""))
+ for key in ("archive_sha256", "binary_sha256")
+ )
+ ):
+ raise ValueError("invalid official VMess peer identity")
+ actual = {r["case_id"]: r for r in results}
+ recalculated = native_results(
+ [c for c in cases if c["case_id"] in NATIVE], report, run_dir / "native"
+ )
+ for case in cases:
+ identifier = case["case_id"]
+ argv = commands(identifier)
+ if not argv:
+ continue
+ records = []
+ events = []
+ for i, command in enumerate(argv):
+ matching = [r for r in run["commands"] if r["name"] == f"{identifier}-{i}"]
+ if len(matching) != 1 or matching[0]["command"] != [
+ redact(part) for part in command
+ ]:
+ raise ValueError("missing VMess gate command")
+ records.extend(matching)
+ path = run_dir / f"{identifier}-{i}-events.jsonl"
+ if path.exists():
+ events.extend(read_events(path))
+ recalculated.append(gate_result(case, records, events))
+ for item in recalculated:
+ if item != actual.get(item["case_id"]):
+ raise ValueError("VMess results disagree with structured observations")
+ names = [c["name"] for c in run["commands"]]
+ needed_commands = {
+ f"{identifier}-{i}"
+ for identifier in GATES
+ for i in range(len(commands(identifier)))
+ } | {
+ "production-build",
+ "offline-scripts",
+ "feature-default",
+ "feature-minimal",
+ *(
+ "feature-" + name
+ for name in (
+ "outbound-trojan",
+ "outbound-vmess",
+ "outbound-hysteria2",
+ "stream-transport",
+ "quic-transport",
+ )
+ ),
+ }
+ if (
+ len(names) != len(set(names))
+ or set(names) != needed_commands
+ or any(
+ c.get("exit_code") != 0
+ or c.get("cleanup") is not True
+ or c.get("log") not in paths
+ for c in run["commands"]
+ )
+ ):
+ raise ValueError("missing or failed VMess validation command")
+ for record in run["commands"]:
+ name = record["name"]
+ if name == "feature-default":
+ expected_command = [
+ "cargo",
+ "test",
+ "--locked",
+ "--test",
+ "feature_foundations",
+ ]
+ elif name.startswith("feature-"):
+ expected_command = [
+ "cargo",
+ "check",
+ "--locked",
+ "--no-default-features",
+ "--lib",
+ ]
+ if name != "feature-minimal":
+ expected_command += ["--features", name.removeprefix("feature-")]
+ elif name == "production-build":
+ expected_command = [
+ "cargo",
+ "build",
+ "--locked",
+ "--release",
+ "--no-default-features",
+ "--features",
+ DEFAULT_FEATURES,
+ "--lib",
+ ]
+ elif name == "offline-scripts":
+ expected_command = [
+ sys.executable,
+ "-m",
+ "vcore_scripts.protocol_script_tests",
+ str(run_dir / "script-tests.json"),
+ ]
+ else:
+ continue
+ if record["command"] != [redact(part) for part in expected_command]:
+ raise ValueError("VMess feature or script command changed")
+ script = read_json(run_dir / "script-tests.json")
+ tests = {t["test"]: t["status"] for t in script["cases"]}
+ if (
+ len(tests) != script["tests_run"]
+ or any(tests.get(name) != "PASS" for name in SCRIPT_OBSERVATIONS.values())
+ or any(status != "PASS" for status in tests.values())
+ ):
+ raise ValueError("missing harness failure-path tests")
+ fields = fields_report(cases, results)
+ if read_json(run_dir / "fields.json") != fields or any(
+ f["status"] != "PASS" for f in fields["fields"]
+ ):
+ raise ValueError("incomplete VMess field coverage")
+ resources = read_events(run_dir / "resources.jsonl")
+ owned = [
+ e
+ for e in resources
+ if e.get("suite") == "VMESS-OWNED" and e.get("status") == "PASS"
+ ]
+ if len(owned) != 40 or not all(idle_resources(e.get("resources")) for e in owned):
+ raise ValueError("missing 20-round owned resource evidence per selected mode")
+ print(
+ f"VMESS: PASS ({len(cases)} required cases; {len(FIELD_IDS)} VMess field rows)"
+ )
diff --git a/scripts/src/vcore_scripts/protocol_vmess_container.py b/scripts/src/vcore_scripts/protocol_vmess_container.py
new file mode 100644
index 0000000..dd3203d
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_vmess_container.py
@@ -0,0 +1,352 @@
+"""VMESS wire cases against official latest peers and entirely isolated origins."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import shutil
+import tempfile
+from pathlib import Path
+
+from .builds import CORE_DIR
+from .mihomo_release import download_mihomo
+from .native_release import PeerArtifact, download_native
+from .protocol_containers import ContainerLab, command
+from .protocol_evidence import read_events
+from .protocol_fixtures import certificates
+from .protocol_inputs import redact, source_identity
+from .protocol_peers import run_command
+from .protocol_vmess import CASES, peer_config
+from .protocol_vmess_public import CASES as PUBLIC_CASES
+from .protocol_vmess_public import events_pass, node_config
+
+ALL_CASES = CASES | PUBLIC_CASES
+
+
+def run(output: Path, selected=None, *, preflight_only=False):
+ selected = list(ALL_CASES) if selected is None else selected
+ if (
+ not selected
+ or len(set(selected)) != len(selected)
+ or not set(selected) <= ALL_CASES.keys()
+ ):
+ raise ValueError("invalid VMESS native selection")
+ output.mkdir(parents=True, exist_ok=False)
+ if preflight_only:
+ # One listener/origin group per official implementation, not a traffic run.
+ kinds = {ALL_CASES[case][0] for case in selected}
+ selected = [
+ next(case for case in selected if ALL_CASES[case][0] == kind)
+ for kind in sorted(kinds)
+ ]
+ report = dict(
+ stage="VMESS",
+ scope="container-wire-and-public-consumer",
+ source=source_identity(),
+ status="NOT RUN",
+ phase="preflight",
+ cases=[],
+ peers={},
+ isolation={},
+ )
+ try:
+ artifacts = {}
+ for kind in sorted({ALL_CASES[case][0] for case in selected} | {"M"}):
+ directory = output / "binaries" / kind
+ if kind == "M":
+ identity = {}
+ binary = download_mihomo(
+ "linux-arm64", directory=directory, identity=identity
+ )
+ artifacts[kind] = PeerArtifact(binary, identity)
+ else:
+ artifacts[kind] = download_native(
+ kind, directory, "linux-arm64", defer_version=True
+ )
+ report["peers"][kind] = artifacts[kind].identity
+ lab = ContainerLab(report["isolation"])
+ report["phase"] = "build"
+ built = run_command(
+ [
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ "vmess_native",
+ "--test",
+ "vmess_public",
+ "--no-run",
+ ],
+ timeout=180,
+ )
+ (output / "build.log").write_text(redact(built.stdout.decode(errors="replace")))
+ if built.returncode != 0 or not built.cleanup:
+ raise RuntimeError("container wire build failed")
+ # Reuse a peer only within one transport; every case gets fresh origin
+ # controls/ports and sessions. One downloaded release snapshot per run.
+ groups = {}
+ for case in selected:
+ kind, mode, encrypted, test = ALL_CASES[case]
+ groups.setdefault((kind, mode, encrypted), []).append((case, test))
+ for (kind, mode, encrypted), cases in groups.items():
+ report["phase"] = "peer-start"
+ with tempfile.TemporaryDirectory(
+ prefix="private-", dir=output
+ ) as temporary:
+ root = Path(temporary)
+ with contextlib.ExitStack() as stack:
+ origin_dir, server_dir = root / "origin", root / "server"
+ origin_dir.mkdir()
+ server_dir.mkdir()
+ shutil.copyfile(
+ Path(__file__).with_name("container_udp_origin.py"),
+ origin_dir / "origin.py",
+ )
+ artifact = artifacts[kind]
+ shutil.copy2(artifact.binary, server_dir / "peer")
+ tag = f"{mode}-{'tls' if encrypted else 'plain'}"
+ origin = lab.start(
+ stack,
+ origin_dir,
+ tag + "-origin",
+ [
+ "env",
+ "VCORE_ISOLATED_ORIGIN=1",
+ "python",
+ "-B",
+ "/data/fixture/origin.py",
+ ],
+ )
+ argv = (
+ [
+ "/data/fixture/peer",
+ "-d",
+ "/data",
+ "-f",
+ "/data/fixture/config.json",
+ ]
+ if kind == "M"
+ else [
+ "/data/fixture/peer",
+ "run",
+ "-c",
+ "/data/fixture/config.json",
+ ]
+ )
+ server = lab.start(stack, server_dir, tag + "-server", argv)
+ version = command(
+ "exec",
+ server.name,
+ "/data/fixture/peer",
+ "-v" if kind == "M" else "version",
+ ).strip()
+ digest = command(
+ "exec", server.name, "sha256sum", "/data/fixture/peer"
+ ).split()[0]
+ if not version or digest != artifact.identity["binary_sha256"]:
+ raise RuntimeError("container peer identity mismatch")
+ artifact.identity["version"] = version
+ # Non-leaf pin still exercises actual certificate name checks.
+ from .protocol_fixtures import certificate_chain
+
+ cert, key, pin = (
+ certificate_chain(server_dir)
+ if encrypted
+ else certificates(server_dir)
+ )
+ config = peer_config(
+ kind,
+ mode,
+ encrypted,
+ 23000,
+ Path("/data/fixture") / cert.name,
+ Path("/data/fixture") / key.name,
+ )
+ if kind == "M":
+ config["hosts"] = {"vcore-fixture.test": origin.ipv4}
+ config["listeners"][0]["listen"] = "::"
+ else:
+ config["dns"]["hosts"] = {"vcore-fixture.test": origin.ipv4}
+ config["inbounds"][0]["listen"] = "::"
+ (server_dir / "config.json").write_text(json.dumps(config))
+ upstream = None
+ node = node_config(mode, encrypted, server.ipv4, pin)
+ hop = None
+ if any(case in PUBLIC_CASES for case, _ in cases):
+ upstream_dir = root / "upstream"
+ upstream_dir.mkdir()
+ shutil.copy2(artifacts["M"].binary, upstream_dir / "peer")
+ upstream = lab.start(
+ stack,
+ upstream_dir,
+ tag + "-upstream",
+ [
+ "/data/fixture/peer",
+ "-d",
+ "/data",
+ "-f",
+ "/data/fixture/config.json",
+ ],
+ )
+ (upstream_dir / "config.json").write_text(
+ json.dumps(
+ {
+ "socks-port": 23001,
+ "allow-lan": True,
+ "bind-address": "*",
+ "log-level": "silent",
+ "ipv6": True,
+ "hosts": {"peer.fixture.test": server.ipv4},
+ "rules": ["MATCH,DIRECT"],
+ }
+ )
+ )
+ hop = dict(
+ name="hop",
+ type="socks5",
+ server=upstream.ipv4,
+ port=23001,
+ udp=True,
+ )
+ upstream.release()
+ upstream.wait_tcp(23001)
+ fixture = root / "input.json"
+ fixture.write_text(
+ json.dumps(
+ dict(
+ isolation="containers",
+ origin_control=f"{origin.ipv4}:24000",
+ origin_ipv4=origin.ipv4,
+ origin_ipv6=origin.ipv6,
+ server_ipv6=server.ipv6,
+ data_dir=str(root / "data"),
+ node=node,
+ hop=hop,
+ peer_kind=kind,
+ )
+ )
+ )
+ origin.release()
+ server.release()
+ origin.wait_tcp(24000)
+ server.wait_tcp(23000)
+ report["phase"] = "execute"
+ for case, test in cases:
+ if preflight_only:
+ continue
+ print(case, flush=True)
+ record = dict(case_id=case, status="NOT RUN", peer_kind=kind)
+ report["cases"].append(record)
+ events = output / f"{case}-events.jsonl"
+ test_command = [
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ "vmess_public" if case in PUBLIC_CASES else "vmess_native",
+ test,
+ "--",
+ "--ignored",
+ "--exact",
+ "--nocapture",
+ ]
+ result = run_command(
+ test_command,
+ cwd=CORE_DIR,
+ timeout=240,
+ limit=4 * 1024 * 1024,
+ env=dict(
+ os.environ,
+ VCORE_VMESS_PEER=f"{server.ipv4}:23000",
+ VCORE_VMESS_TRANSPORT=json.dumps(
+ dict(
+ mode=mode,
+ tls=encrypted,
+ pin=pin,
+ peer_kind=kind,
+ udp_path_limit=15000,
+ )
+ ),
+ VCORE_VMESS_ORIGIN_V4=origin.ipv4,
+ VCORE_VMESS_AB_INPUT=str(fixture),
+ VCORE_CASE_EVENTS=str(events),
+ ),
+ )
+ (output / f"{case}.log").write_text(
+ redact(result.stdout.decode(errors="replace"))
+ )
+ observed = read_events(events) if events.exists() else []
+ record.update(
+ command=test_command,
+ exit_code=result.returncode,
+ seconds=result.seconds,
+ command_cleanup=result.cleanup,
+ status="PASS"
+ if result.returncode == 0
+ and result.cleanup
+ and (
+ events_pass(observed, test)
+ if case in PUBLIC_CASES
+ else observed
+ == [
+ dict(
+ schema_version=1,
+ suite="VMESS-WIRE",
+ assertion=test,
+ status=status,
+ )
+ for status in ("BEGIN", "PASS")
+ ]
+ )
+ else "FAIL",
+ )
+ server.ensure_alive()
+ origin.ensure_alive()
+ print(f"{case}: {record['status']}", flush=True)
+ for case, _ in cases:
+ if preflight_only:
+ continue
+ next(item for item in report["cases"] if item["case_id"] == case)[
+ "cleanup"
+ ] = all(
+ peer.record["joined"]
+ for peer in [server, origin] + ([upstream] if upstream else [])
+ )
+ report["status"] = (
+ "READY"
+ if preflight_only
+ else "PASS"
+ if (preflight_only or len(report["cases"]) == len(selected))
+ and all(case["status"] == "PASS" for case in report["cases"])
+ else "FAIL"
+ )
+ except KeyboardInterrupt:
+ report.update(status="INTERRUPTED", reason="user interruption")
+ except (OSError, RuntimeError, ValueError, KeyError) as error:
+ report.update(
+ status="BLOCKED" if report["phase"] == "preflight" else "FAIL",
+ reason=str(error)
+ if isinstance(error, RuntimeError)
+ else type(error).__name__,
+ )
+ finally:
+ report["cleanup"] = all(
+ peer["joined"] for peer in report["isolation"].get("peers", [])
+ )
+ report["source_unchanged"] = (
+ source_identity()["source_tree_sha256"]
+ == report["source"]["source_tree_sha256"]
+ )
+ if report["status"] in {"PASS", "READY"} and not (
+ report["cleanup"] and report["source_unchanged"]
+ ):
+ report["status"] = "FAIL"
+ (output / "vmess-results.json").write_text(json.dumps(report, indent=2) + "\n")
+ return (
+ 0
+ if report["status"] in {"PASS", "READY"}
+ else (130 if report["status"] == "INTERRUPTED" else 1)
+ )
diff --git a/scripts/src/vcore_scripts/protocol_vmess_public.py b/scripts/src/vcore_scripts/protocol_vmess_public.py
new file mode 100644
index 0000000..580cf4f
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_vmess_public.py
@@ -0,0 +1,153 @@
+"""Required public-consumer cases, independent of the persisted manifest."""
+
+from .protocol_evidence import idle_resources
+
+CASES = {
+ "VMESS-PUBLIC-UDP-FIRST": ("M", "tcp", False, "public_udp_first_response"),
+ "VMESS-PUBLIC-BODY-OPTIONS": ("M", "tcp", False, "public_body_options"),
+}
+CASES["VMESS-PUBLIC-WS-ALPN"] = ("M", "ws-alpn", True, "public_alpn_rejection")
+for mode in ("tcp", "ws", "grpc", "http", "h2"):
+ kind = "V2" if mode in {"http", "h2"} else "M"
+ for tls in (False, True):
+ label = f"VMESS-PUBLIC-{mode.upper()}-{'TLS' if tls else 'PLAIN'}"
+ for suffix, test in (
+ ("BASE", "public_base"),
+ ("NEG", "public_negative"),
+ ("GRAPH", "runtime::public_graph"),
+ ("IPV6", "runtime::public_ipv6_and_gates"),
+ ("ENTRYPOINTS", "runtime::public_entrypoints"),
+ ):
+ CASES[label + "-" + suffix] = (kind, mode, tls, test)
+for mode in ("tcp", "grpc"):
+ for suffix, test in (
+ ("LIFE", "runtime::public_lifecycle"),
+ ("OWNED", "runtime::owned_resources"),
+ ):
+ CASES[f"VMESS-PUBLIC-{mode.upper()}-{suffix}"] = ("M", mode, True, test)
+for mode in ("tcp", "ws", "grpc"):
+ CASES[f"VMESS-REGRESSION-TROJAN-{mode.upper()}"] = (
+ "M",
+ "trojan-" + mode,
+ True,
+ "public_legacy_regression",
+ )
+ CASES[f"VMESS-PUBLIC-{mode.upper()}-UDP-ISOLATION"] = (
+ "M",
+ mode,
+ True,
+ "runtime::public_udp_isolation",
+ )
+for mode in ("ws-ed-1", "ws-ed-2048", "ws-header", "ws-path", "grpc-custom"):
+ kind = "V2" if mode in {"ws-header", "ws-path"} else "M"
+ CASES[f"VMESS-PUBLIC-{mode.upper()}"] = (kind, mode, True, "public_base")
+
+
+def node_config(mode, tls, host, pin):
+ if mode.startswith("trojan-"):
+ node = node_config(mode.removeprefix("trojan-"), tls, host, pin)
+ node.update(
+ type="trojan",
+ password="synthetic-regression-only",
+ sni=node.pop("servername"),
+ )
+ for key in ("uuid", "tls"):
+ node.pop(key)
+ return node
+ network = mode.split("-")[0]
+ node = dict(
+ name="peer",
+ type="vmess",
+ server=host,
+ port=23000,
+ uuid="07070707-0707-0707-0707-070707070707",
+ udp=True,
+ network=network,
+ tls=tls,
+ )
+ if tls:
+ node.update(servername="localhost", fingerprint=pin)
+ node["alpn"] = ["h2" if network in {"grpc", "h2"} else "http/1.1"]
+ if network == "ws":
+ node["ws-opts"] = {
+ "path": "/vmess-ws",
+ "headers": {"Host": "localhost", "X-Fixture": "exact-value"},
+ }
+ if mode == "ws-alpn":
+ node["alpn"] = ["h2", "http/1.1"]
+ if mode.startswith("ws-ed"):
+ node["ws-opts"]["max-early-data"] = int(mode.split("-")[-1])
+ elif mode in {"ws-header", "ws-path"}:
+ node["ws-opts"].update(
+ {
+ "path": "/vmess-ws/",
+ "max-early-data": 2048,
+ "early-data-header-name": "X-Vcore-Ed"
+ if mode == "ws-header"
+ else "",
+ }
+ )
+ elif network == "grpc":
+ node["grpc-opts"] = {
+ "grpc-service-name": "/vmess-grpc/Tun"
+ if mode == "grpc-custom"
+ else "vmess-grpc"
+ }
+ elif network == "http":
+ node["http-opts"] = {
+ "method": "POST",
+ "path": ["/vmess-http"],
+ "headers": {"Host": ["localhost"], "X-Fixture": ["exact-value"]},
+ }
+ elif network == "h2":
+ node["h2-opts"] = {"host": ["localhost"], "path": "/vmess-h2"}
+ return node
+
+
+def pairs(events, suite, assertion, count):
+ selected = [
+ e for e in events if e.get("suite") == suite and e.get("assertion") == assertion
+ ]
+ return len(selected) == count * 2 and all(
+ e.get("status") == ("BEGIN" if i % 2 == 0 else "PASS")
+ for i, e in enumerate(selected)
+ )
+
+
+def events_pass(events, test):
+ main = [event for event in events if event.get("suite") == "VMESS-PUBLIC"]
+ if len(main) != 2 or not pairs(main, "VMESS-PUBLIC", test, 1):
+ return False
+ if any(
+ event.get("schema_version") != 1 or event.get("status") not in {"BEGIN", "PASS"}
+ for event in events
+ ):
+ return False
+ if test == "public_base" and not (
+ pairs(events, "VMESS-BASE", "tcp_10mib_both_directions", 3)
+ and pairs(events, "VMESS-BASE", "udp_each_codec_and_family", 3)
+ ):
+ return False
+ if test in {"runtime::public_lifecycle", "runtime::owned_resources"}:
+ suite = "VMESS-LIFE" if test.endswith("public_lifecycle") else "VMESS-OWNED"
+ if not pairs(events, suite, "stop_and_remain_quiet", 20):
+ return False
+ for end in [
+ e for e in events if e.get("suite") == suite and e["status"] == "PASS"
+ ]:
+ if end.get("seconds", 0) < 5:
+ return False
+ if suite == "VMESS-OWNED":
+ checkpoints = end.get("checkpoints", [])
+ points = {p["phase"]: p["resources"] for p in checkpoints}
+ if (
+ len(checkpoints) != 3
+ or set(points) != {"baseline", "after-stop", "quiet"}
+ or not all(idle_resources(p) for p in points.values())
+ or points["after-stop"] != points["quiet"]
+ or not idle_resources(end.get("resources"))
+ ):
+ return False
+ return test != "public_body_options" or pairs(
+ events, "VMESS-BODY", "config_controls_aead_body", 14
+ )
diff --git a/scripts/src/vcore_scripts/protocol_vmess_udp_ab.py b/scripts/src/vcore_scripts/protocol_vmess_udp_ab.py
new file mode 100644
index 0000000..484954c
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_vmess_udp_ab.py
@@ -0,0 +1,88 @@
+"""Container-only matched UDP diagnostic, not VMESS stage acceptance."""
+
+from __future__ import annotations
+
+import argparse
+import itertools
+import re
+import sys
+from pathlib import Path
+
+from .mihomo_isolation import exclusive_run
+
+
+def options(codecs):
+ return [
+ dict(codec=codec, cipher=cipher, padding=padding, length=length)
+ for codec, cipher, padding, length in itertools.product(
+ codecs,
+ ["none", "auto", "aes-128-gcm", "chacha20-poly1305"],
+ [False, True],
+ [False, True],
+ )
+ if cipher != "none" or not (padding or length)
+ ]
+
+
+def warning_summary(path):
+ lines = path.read_text(errors="replace").splitlines()
+ loopbacks = []
+ for line in lines:
+ if "reject loopback connection" in line:
+ endpoints = re.findall(
+ r"(?:\[[0-9a-fA-F:]+\]|(?:[a-zA-Z0-9_-]+\.)+[a-zA-Z0-9_-]+):(\d+)\b",
+ line,
+ )
+ loopbacks.append(dict(ports=[int(port) for port in endpoints]))
+ return dict(lines=len(lines), loopback_rejections=loopbacks)
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("output", type=Path)
+ parser.add_argument(
+ "--modes",
+ nargs="+",
+ choices=["tcp", "ws", "grpc"],
+ default=["tcp", "ws", "grpc"],
+ )
+ parser.add_argument(
+ "--tls", nargs="+", choices=["plain", "tls"], default=["plain", "tls"]
+ )
+ parser.add_argument(
+ "--codecs",
+ nargs="+",
+ choices=["raw", "xudp", "packetaddr"],
+ default=["raw", "xudp", "packetaddr"],
+ )
+ parser.add_argument(
+ "--families",
+ nargs="+",
+ choices=["ipv4", "ipv6", "domain"],
+ default=["ipv4", "ipv6", "domain"],
+ )
+ parser.add_argument("--rounds", type=int, choices=range(1, 21), default=2)
+ parser.add_argument("--packets", type=int, choices=range(1, 101), default=100)
+ parser.add_argument("--sizes", nargs="+", type=int)
+ parser.add_argument("--include-boundary", action="store_true")
+ parser.add_argument("--collision-probe", action="store_true")
+ parser.add_argument("--socket-probe", action="store_true")
+ parser.add_argument("--nat-reuse-probe", action="store_true")
+ args = parser.parse_args()
+ if args.collision_probe or args.socket_probe:
+ parser.error("BLOCKED: archived host-server probes require container migration")
+ if args.sizes and any(size < 1 or size > 15000 for size in args.sizes):
+ parser.error("sizes must be between 1 and the 15000-byte fixture budget")
+ args.tls = [value == "tls" for value in args.tls]
+ if args.nat_reuse_probe:
+ args.modes, args.tls, args.codecs = ["tcp"], [False], ["raw", "xudp"]
+ args.rounds, args.packets, args.sizes, args.families = 1, 1, [1], ["ipv4"]
+ args.include_boundary = False
+ from .protocol_vmess_udp_container import run as container_run
+
+ with exclusive_run():
+ return container_run(args)
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/src/vcore_scripts/protocol_vmess_udp_container.py b/scripts/src/vcore_scripts/protocol_vmess_udp_container.py
new file mode 100644
index 0000000..bab7145
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_vmess_udp_container.py
@@ -0,0 +1,382 @@
+"""Container-only VMESS UDP differential; not public-runtime or stage acceptance."""
+
+from __future__ import annotations
+
+import contextlib
+import itertools
+import json
+import os
+import shutil
+import tempfile
+from pathlib import Path
+
+from .builds import CORE_DIR
+from .mihomo_release import download_mihomo
+from .protocol_containers import ContainerLab, command
+from .protocol_fixtures import certificates
+from .protocol_inputs import redact, source_identity
+from .protocol_peers import run_command
+from .protocol_vmess import peer_config
+from .protocol_vmess_udp_ab import options, warning_summary
+
+
+def client_config(matrix, mode, encrypted, server, origin, client, pin):
+ listeners, nodes, selected = [], [], []
+ for index, option in enumerate(matrix):
+ port = 25000 + index
+ selected.append(dict(option, socks_port=port, socks_host=client))
+ node = dict(
+ name=f"edge-{index}",
+ type="vmess",
+ server=server,
+ port=23000,
+ uuid="07070707-0707-0707-0707-070707070707",
+ alterId=0,
+ cipher=option["cipher"],
+ network=mode,
+ tls=encrypted,
+ udp=True,
+ )
+ node.update(
+ {
+ "global-padding": option["padding"],
+ "authenticated-length": option["length"],
+ }
+ )
+ if option["codec"] != "raw":
+ node["packet-encoding"] = option["codec"]
+ if encrypted:
+ node.update(servername="localhost", fingerprint=pin)
+ if mode == "ws":
+ node["ws-opts"] = dict(path="/vmess-ws", headers={"Host": "localhost"})
+ if mode == "grpc":
+ node["grpc-opts"] = {"grpc-service-name": "vmess-grpc"}
+ nodes.append(node)
+ listeners.append(
+ dict(
+ name=f"fixture-{index}",
+ type="socks",
+ listen=client,
+ port=port,
+ udp=True,
+ proxy=node["name"],
+ )
+ )
+ return {
+ "mode": "rule",
+ "log-level": "warning",
+ "ipv6": True,
+ "hosts": {"vcore-fixture.test": origin},
+ "listeners": listeners,
+ "proxies": nodes,
+ "rules": ["MATCH,REJECT"],
+ }, selected
+
+
+def run(args):
+ output = args.output.resolve()
+ output.mkdir(parents=True, exist_ok=False)
+ matrix = options(args.codecs)
+ sizes = args.sizes or [1, 64, 512, 1200]
+ boundary = args.include_boundary or args.sizes is None
+ report = dict(
+ scope="container-matched-mihomo-vcore-udp-diagnostic",
+ status="NOT RUN",
+ phase="preflight",
+ source=source_identity(),
+ cases=[],
+ isolation={},
+ peer={},
+ cleanup=False,
+ rounds=args.rounds,
+ packets_per_size=args.packets,
+ sizes=sizes,
+ include_boundary=boundary,
+ boundary_policy="raw/XUDP: 15000; packetaddr: 15000 minus 7/19 address bytes",
+ families=args.families,
+ options=matrix,
+ nat_reuse_probe=args.nat_reuse_probe,
+ fixture_source_policy="distinct SOCKS UDP sockets retained until transport end",
+ notes=[
+ "Separate owned VMs: protocol server, official client ingress, UDP origin.",
+ "Host runs VCore and test driver only; no published host/server ports.",
+ "Same body flags, families, sizes, packet count; order alternates.",
+ "Send, origin observation and reply each retain their 1s deadline.",
+ "Origin now echoes autonomously and reports exact received bytes via TCP.",
+ "Failed associations stop without retries; loopback protection unchanged.",
+ "Virtual IPv6 and wire diagnostic do not prove device or VMESS acceptance.",
+ ],
+ )
+ try:
+ binary = download_mihomo(
+ "linux-arm64", directory=output / "binary", identity=report["peer"]
+ )
+ lab = ContainerLab(report["isolation"])
+ report["phase"] = "build"
+ build = run_command(
+ [
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ "vmess_native",
+ "--no-run",
+ ],
+ cwd=CORE_DIR,
+ timeout=180,
+ )
+ (output / "build.log").write_text(redact(build.stdout.decode(errors="replace")))
+ if build.returncode != 0 or not build.cleanup:
+ raise RuntimeError("diagnostic build failed")
+ for mode, encrypted in itertools.product(args.modes, args.tls):
+ name = f"{mode}-{'tls' if encrypted else 'plain'}"
+ record = dict(name=name, status="NOT RUN")
+ report["cases"].append(record)
+ report["phase"] = "peer-start"
+ print(f"UDP-CONTAINERS: {name}", flush=True)
+ with tempfile.TemporaryDirectory(
+ prefix="private-", dir=output
+ ) as temporary:
+ root = Path(temporary)
+ with contextlib.ExitStack() as stack:
+ directories = {}
+ peers = {}
+ for role in ["origin", "server", "client"]:
+ directory = root / role
+ directory.mkdir()
+ directories[role] = directory
+ if role == "origin":
+ shutil.copyfile(
+ Path(__file__).with_name("container_udp_origin.py"),
+ directory / "origin.py",
+ )
+ argv = [
+ "env",
+ "VCORE_ISOLATED_ORIGIN=1",
+ "python",
+ "-B",
+ "/data/fixture/origin.py",
+ ]
+ else:
+ shutil.copy2(binary, directory / "mihomo")
+ argv = [
+ "/data/fixture/mihomo",
+ "-d",
+ "/data",
+ "-f",
+ "/data/fixture/config.json",
+ ]
+ peers[role] = lab.start(
+ stack, directory, f"{name}-{role}", argv
+ )
+ origin, server, client = (
+ peers[key] for key in ["origin", "server", "client"]
+ )
+ version = command(
+ "exec", server.name, "/data/fixture/mihomo", "-v"
+ ).strip()
+ digest = command(
+ "exec", server.name, "sha256sum", "/data/fixture/mihomo"
+ ).split()[0]
+ if digest != report["peer"]["binary_sha256"]:
+ raise RuntimeError(
+ "container peer identity differs from download"
+ )
+ report["peer"]["version"] = version
+ record["peer_version"] = version
+ record["origin_python"] = command(
+ "exec", origin.name, "python", "--version"
+ ).strip()
+ cert, key, pin = certificates(directories["server"])
+ config = peer_config(
+ "M",
+ mode,
+ encrypted,
+ 23000,
+ Path("/data/fixture") / cert.name,
+ Path("/data/fixture") / key.name,
+ )
+ config["log-level"] = "warning"
+ config["hosts"] = {"vcore-fixture.test": origin.ipv4}
+ config["listeners"][0]["listen"] = server.ipv4
+ (directories["server"] / "config.json").write_text(
+ json.dumps(config)
+ )
+ config, selected = client_config(
+ matrix,
+ mode,
+ encrypted,
+ server.ipv4,
+ origin.ipv4,
+ client.ipv4,
+ pin,
+ )
+ (directories["client"] / "config.json").write_text(
+ json.dumps(config)
+ )
+ for peer in peers.values():
+ peer.release()
+ origin.wait_tcp(24000)
+ server.wait_tcp(23000)
+ for option in selected:
+ client.wait_tcp(option["socks_port"])
+ report["phase"] = "execute"
+ fixture = root / "input.json"
+ fixture.write_text(
+ json.dumps(
+ dict(
+ isolation="containers",
+ origin_control=f"{origin.ipv4}:24000",
+ origin_ipv4=origin.ipv4,
+ origin_ipv6=origin.ipv6,
+ options=selected,
+ rounds=args.rounds,
+ packets_per_size=args.packets,
+ sizes=sizes,
+ include_boundary=boundary,
+ families=args.families,
+ )
+ )
+ )
+ events = output / f"{name}.jsonl"
+ test_command = [
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ "vmess_native",
+ "udp_ab::socks_nat_source_reuse"
+ if args.nat_reuse_probe
+ else "udp_ab::matched_clients",
+ "--",
+ "--ignored",
+ "--exact",
+ "--nocapture",
+ ]
+ execution = run_command(
+ test_command,
+ cwd=CORE_DIR,
+ timeout=600,
+ limit=4 * 1024 * 1024,
+ env=dict(
+ os.environ,
+ VCORE_VMESS_PEER=f"{server.ipv4}:23000",
+ VCORE_VMESS_TRANSPORT=json.dumps(
+ dict(mode=mode, tls=encrypted, pin=pin)
+ ),
+ VCORE_VMESS_ORIGIN_V4=origin.ipv4,
+ VCORE_VMESS_AB_INPUT=str(fixture),
+ VCORE_VMESS_AB_EVENTS=str(events),
+ VCORE_VMESS_AB_PRIVATE=str(root),
+ ),
+ )
+ (output / f"{name}.log").write_text(
+ redact(execution.stdout.decode(errors="replace"))
+ )
+ observations = (
+ [json.loads(line) for line in events.read_text().splitlines()]
+ if events.exists()
+ else []
+ )
+ expected = (
+ 3
+ if args.nat_reuse_probe
+ else args.rounds * len(matrix) * len(args.families) * 2
+ )
+ record.update(
+ command=test_command,
+ exit_code=execution.returncode,
+ seconds=execution.seconds,
+ command_cleanup=execution.cleanup,
+ expected_associations=expected,
+ observed_associations=len(observations),
+ failures=[
+ item for item in observations if item["status"] != "PASS"
+ ],
+ clients={
+ kind: dict(
+ associations=sum(
+ item["client"] == kind for item in observations
+ ),
+ failed=sum(
+ item["client"] == kind and item["status"] != "PASS"
+ for item in observations
+ ),
+ completed_packets=sum(
+ item["completed"]
+ for item in observations
+ if item["client"] == kind
+ ),
+ )
+ for kind in ["vcore", "mihomo"]
+ },
+ )
+ for peer in peers.values():
+ peer.ensure_alive()
+ # Stop/delete VMs and join bounded log readers before inspection.
+ for role in ["server", "client"]:
+ record[f"{role}_warnings"] = warning_summary(
+ directories[role] / "peer.log"
+ )
+ record["cleanup"] = all(
+ peer.record["joined"] for peer in peers.values()
+ )
+ expected_outcome = (
+ [item["status"] for item in observations]
+ == ["PASS", "REPRODUCED", "PASS"]
+ if args.nat_reuse_probe
+ else not record["failures"]
+ )
+ record["status"] = (
+ ("REPRODUCED" if args.nat_reuse_probe else "PASS")
+ if (
+ execution.returncode == 0
+ and execution.cleanup
+ and record["cleanup"]
+ and len(observations) == expected
+ and expected_outcome
+ and all(
+ item.get("driver_joined", True) for item in observations
+ )
+ )
+ else "FAIL"
+ )
+ print(
+ json.dumps(
+ {key: record[key] for key in ["name", "status", "clients"]}
+ ),
+ flush=True,
+ )
+ expected_status = "REPRODUCED" if args.nat_reuse_probe else "PASS"
+ report["status"] = (
+ expected_status
+ if report["cases"]
+ and all(case["status"] == expected_status for case in report["cases"])
+ else "FAIL"
+ )
+ except KeyboardInterrupt:
+ report.update(status="INTERRUPTED", reason="user interruption")
+ except (OSError, RuntimeError, ValueError, KeyError) as error:
+ status = "BLOCKED" if report["phase"] == "preflight" else "FAIL"
+ report.update(status=status, reason=type(error).__name__)
+ print(f"UDP-CONTAINERS {status}: {type(error).__name__}", flush=True)
+ finally:
+ report["cleanup"] = all(
+ peer["joined"] for peer in report["isolation"].get("peers", [])
+ )
+ report["source_unchanged"] = (
+ source_identity()["source_tree_sha256"]
+ == report["source"]["source_tree_sha256"]
+ )
+ if report["status"] in {"PASS", "REPRODUCED"} and not (
+ report["cleanup"] and report["source_unchanged"]
+ ):
+ report["status"] = "FAIL"
+ (output / "udp-ab.json").write_text(json.dumps(report, indent=2) + "\n")
+ return (
+ 0
+ if report["status"] == "PASS"
+ else (130 if report["status"] == "INTERRUPTED" else 1)
+ )
diff --git a/scripts/src/vcore_scripts/protocol_xhttp_acceptance.py b/scripts/src/vcore_scripts/protocol_xhttp_acceptance.py
new file mode 100644
index 0000000..da32975
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_xhttp_acceptance.py
@@ -0,0 +1,660 @@
+"""XHTTP execution and independently recomputed, fail-closed stage evidence."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from .builds import DEFAULT_FEATURES
+from .protocol_evidence import HEX, idle_resources, new_result, read_events, read_json
+from .protocol_inputs import redact
+from .protocol_vless_acceptance import commands as previous_commands
+from .protocol_xhttp_catalog import (
+ FIELD_IDS,
+ GATES,
+ NATIVE,
+ OBSERVATIONS,
+ REPRESENTATIVES,
+ SECURITY,
+ UNIT_TESTS,
+ definitions,
+)
+from .protocol_xhttp_fields import PUBLIC_TESTS, events_pass, public_events_pass
+
+
+def test_command(test):
+ return [
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ "vless_public" if test in PUBLIC_TESTS else "xhttp_native",
+ test,
+ "--",
+ "--exact",
+ "--ignored",
+ "--nocapture",
+ ]
+
+
+def commands(identifier):
+ cargo = ["cargo", "test", "--locked", "--all-features"]
+ if identifier in {"XHTTP-CFG", "XHTTP-UNIT", "XHTTP-RELEASE"}:
+ names = list(UNIT_TESTS)
+ if identifier == "XHTTP-CFG":
+ names = names[:2]
+ elif identifier == "XHTTP-UNIT":
+ names = names[2:]
+ flags = ["--release"] if identifier == "XHTTP-RELEASE" else []
+ selected = sum((["--test", name] for name in names), [])
+ result = [cargo + flags + selected]
+ if identifier != "XHTTP-CFG":
+ result += [
+ cargo + flags + ["--lib", "transport::xhttp::tests::"],
+ cargo + flags + ["--lib", "transport::sing_mux::"],
+ cargo + flags + ["--test", "vless_lifecycle"],
+ ]
+ return result
+ if identifier == "XHTTP-REGRESSION":
+ return sum(
+ (
+ previous_commands("VLESS-" + part)
+ for part in ("REGRESSION", "CODEC", "TRANSPORT", "VISION")
+ ),
+ [],
+ )
+ if identifier == "XHTTP-QUALITY":
+ return previous_commands("VLESS-QUALITY") + [
+ [
+ "cargo",
+ "test",
+ "--locked",
+ "--manifest-path",
+ "crates/vcore-netstack/Cargo.toml",
+ "--all-targets",
+ ],
+ [
+ "cargo",
+ "clippy",
+ "--locked",
+ "--manifest-path",
+ "crates/vcore-netstack/Cargo.toml",
+ "--all-targets",
+ "--",
+ "-D",
+ "warnings",
+ ],
+ ]
+ return []
+
+
+def gate_result(case, records, events):
+ result = new_result(case)
+ good = bool(records) and all(
+ r.get("exit_code") == 0 and r.get("cleanup") is True for r in records
+ )
+ assertions = {}
+ for name in case["expected_observation"]:
+ observed = [e for e in events if e.get("assertion") == name]
+ assertions[name] = len(observed) == 2 and [
+ e.get("status") for e in observed
+ ] == ["BEGIN", "PASS"]
+ if case["case_id"] not in OBSERVATIONS:
+ assertions = dict.fromkeys(case["expected_observation"], good)
+ else:
+ good &= all(assertions.values()) and all(
+ e.get("schema_version") == 1 and e.get("status") in {"BEGIN", "PASS"}
+ for e in events
+ )
+ if case["case_id"] != "XHTTP-REGRESSION":
+ unit = [e for e in events if e.get("suite") == "XHTTP-UNIT"]
+ good &= len(unit) == 2 * len(assertions) and all(
+ e["assertion"] in assertions for e in unit
+ )
+ result.update(
+ status="PASS" if good else "FAIL",
+ assertions=assertions,
+ evidence=case["required_evidence"] if good else [],
+ command_exit_code=0 if good else 1,
+ cleanup=bool(records) and all(r.get("cleanup") is True for r in records),
+ )
+ return result
+
+
+def native_results(cases, report, directory, *, allow_partial=False):
+ records = report.get("cases", [])
+ expected = {case["case_id"] for case in cases}
+ actual = {r.get("case_id") for r in records}
+ if (
+ len(records) != len(actual)
+ or not actual <= expected
+ or (not allow_partial and actual != expected)
+ ):
+ raise ValueError("missing, duplicate or unknown XHTTP native case")
+ by_id = {record["case_id"]: record for record in records}
+ output = []
+ for case in cases:
+ identifier = case["case_id"]
+ if identifier not in by_id:
+ continue
+ record = by_id[identifier]
+ variant, test = NATIVE[identifier]
+ path = directory / f"{identifier}-events.jsonl"
+ observed = read_events(path) if path.exists() else []
+ observed_ok = (
+ public_events_pass(observed, test)
+ if test in PUBLIC_TESTS
+ else events_pass(observed, test, owned=test.startswith("lifecycle::"))
+ )
+ clean = record.get("command_cleanup") is True and report.get("cleanup") is True
+ good = (
+ observed_ok
+ and clean
+ and report.get("source_unchanged") is True
+ and record.get("status") == "PASS"
+ and record.get("exit_code") == 0
+ and record.get("command") == test_command(test)
+ and record.get("assertion") == test
+ and record.get("variant") == variant
+ )
+ if test.startswith("close::"):
+ path = directory / f"{variant}-close-reference.json"
+ reference = read_json(path) if path.exists() else {}
+ good &= (
+ reference.get("scope") == "same-mode"
+ and reference.get("terminated") is True
+ and reference.get("tail_hex") == ""
+ )
+ result = new_result(case)
+ result.update(
+ status="PASS" if good else "FAIL",
+ assertions={test: observed_ok},
+ evidence=case["required_evidence"] if good else [],
+ command_exit_code=record.get("exit_code"),
+ cleanup=clean,
+ )
+ output.append(result)
+ return output
+
+
+def security_results(cases, report, directory, *, allow_partial=False):
+ from .protocol_xhttp_security import security_cases
+
+ expected = {}
+ identity = {
+ k: {"certificate": "fixture", "private-key": "fixture"}
+ for k in ("valid", "absent", "expired", "wrong-ca")
+ }
+ for case in cases:
+ version = SECURITY[case["case_id"]]
+ base = dict(
+ alpn=["http/1.1" if version == "h1" else version],
+ certificate="fixture",
+ **{"private-key": "fixture", "xhttp-opts": {}},
+ )
+ expected[version] = {
+ f"{version}-{name}": failure
+ for name, _, _, failure in security_cases(
+ base, identity, identity["valid"], "2001:db8::1"
+ )
+ }
+ records = report.get("cases", [])
+ ids = set().union(*(set(e) for e in expected.values()))
+ actual = {r.get("case_id") for r in records}
+ if (
+ len(records) != len(actual)
+ or not actual <= ids
+ or (not allow_partial and actual != ids)
+ ):
+ raise ValueError("missing, duplicate or unknown XHTTP security case")
+ results = []
+ by_id = {r["case_id"]: r for r in records}
+ for case in cases:
+ version = SECURITY[case["case_id"]]
+ if allow_partial and not actual.intersection(expected[version]):
+ continue
+ clean = report.get("cleanup") is True and report.get("owned_remaining") == []
+ good = clean and report.get("source_unchanged") is True
+ for name, failure in expected[version].items():
+ record = by_id.get(name, {})
+ path = directory / f"{name}-events.jsonl"
+ events = read_events(path) if path.exists() else []
+ good &= (
+ events_pass(events, "security::native_xhttp_security")
+ and record.get("exit_code") == 0
+ and record.get("command_cleanup") is True
+ and record.get("command")
+ == test_command("security::native_xhttp_security")
+ and record.get("status") == "PASS"
+ )
+ if version == "h3" and failure:
+ category = {
+ "absent": "certificate_required",
+ "expired": "certificate_expired",
+ "wrong-ca": "unknown_ca",
+ }[failure]
+ good &= record.get("identity_enforced") is True and any(
+ e.get("category") == category
+ for e in record.get("certificate_errors", [])
+ )
+ result = new_result(case)
+ result.update(
+ status="PASS" if good else "FAIL",
+ assertions={case["case_id"]: good},
+ evidence=case["required_evidence"] if good else [],
+ command_exit_code=0 if good else 1,
+ cleanup=clean,
+ )
+ results.append(result)
+ return results
+
+
+def fields_report(cases, results):
+ statuses = {r["case_id"]: r["status"] for r in results}
+ complete = set(statuses) == {c["case_id"] for c in definitions()} and all(
+ s == "PASS" for s in statuses.values()
+ )
+ fields = []
+ for row in sorted(FIELD_IDS):
+ owners = [c["case_id"] for c in cases if row in c["row_ids"]]
+ behavior = [c for c in owners if c in NATIVE or c in SECURITY]
+ fields.append(
+ dict(
+ row_id=row,
+ required_cases=owners,
+ status="PASS"
+ if complete and behavior and "XHTTP-CFG" in owners
+ else "NOT RUN",
+ )
+ )
+ return dict(schema_version=1, stage="XHTTP", protocol="vless", fields=fields)
+
+
+def prepare_peers(output, kinds):
+ from .caddy_build import build_caddy
+ from .mihomo_release import download_mihomo
+ from .native_release import download_native
+
+ supplied = {}
+ for kind in sorted(kinds):
+ directory = output / "binaries" / kind
+ if kind == "M":
+ identity = {}
+ binary = download_mihomo(
+ "linux-arm64", directory=directory, identity=identity
+ )
+ supplied[kind] = binary, identity
+ else:
+ artifact = (
+ build_caddy(directory)
+ if kind == "Caddy"
+ else download_native(kind, directory, "linux-arm64", defer_version=True)
+ )
+ supplied[kind] = artifact.binary, artifact.identity
+ return supplied
+
+
+def preflight(output):
+ """Only verify the XHTTP native artifacts inside an owned isolated guest."""
+ import shutil
+ import tempfile
+ from contextlib import ExitStack
+
+ from .protocol_containers import ContainerLab, command
+ from .protocol_inputs import CORE_DIR
+
+ supplied = prepare_peers(output, {"M", "XR", "V2", "Caddy"})
+ isolation = {}
+ lab = ContainerLab(isolation, mtu=1500)
+ try:
+ with tempfile.TemporaryDirectory(
+ prefix="xhttp-preflight-", dir=CORE_DIR / "target"
+ ) as tmp:
+ from pathlib import Path
+
+ root = Path(tmp)
+ for kind, (binary, _) in supplied.items():
+ shutil.copy2(binary, root / kind)
+ with ExitStack() as stack:
+ peer = lab.start(
+ stack,
+ root,
+ "preflight",
+ ["python", "-c", "import time; time.sleep(600)"],
+ )
+ peer.release()
+ for kind, (_, identity) in supplied.items():
+ binary = "/data/fixture/" + kind
+ version = command(
+ "exec", peer.name, binary, "-v" if kind == "M" else "version"
+ ).strip()
+ digest = command("exec", peer.name, "sha256sum", binary).split()[0]
+ if not version or digest != identity["binary_sha256"]:
+ raise RuntimeError("isolated XHTTP artifact identity mismatch")
+ identity["version"] = version
+ finally:
+ (output / "peers.json").write_text(
+ json.dumps({k: i for k, (_, i) in supplied.items()}, indent=2) + "\n"
+ )
+ (output / "preflight.json").write_text(
+ json.dumps(
+ dict(
+ scope="preflight-only",
+ wire_acceptance="NOT RUN",
+ isolation=isolation,
+ ),
+ indent=2,
+ )
+ + "\n"
+ )
+
+
+def execute(cases, run, output, results):
+ from .protocol_harness import _command, _features, _scripts
+ from .protocol_xhttp_fields import run as fields_run
+ from .protocol_xhttp_security import run as security_run
+
+ for case in cases:
+ identifier = case["case_id"]
+ if identifier not in GATES:
+ continue
+ if identifier == "XHTTP-FEATURES":
+ result = _features(case, run, output)
+ for name, command in (
+ (
+ "feature-outbound-vless",
+ [
+ "cargo",
+ "check",
+ "--locked",
+ "--no-default-features",
+ "--lib",
+ "--features",
+ "outbound-vless",
+ ],
+ ),
+ (
+ "production-build",
+ [
+ "cargo",
+ "build",
+ "--locked",
+ "--release",
+ "--no-default-features",
+ "--features",
+ DEFAULT_FEATURES,
+ "--lib",
+ ],
+ ),
+ ):
+ observed = _command(run, output, name, command, 1200)
+ if observed.returncode or not observed.cleanup:
+ result.update(
+ status="FAIL",
+ command_exit_code=observed.returncode,
+ cleanup=observed.cleanup,
+ )
+ results[identifier] = result
+ elif identifier == "XHTTP-SCRIPTS":
+ results[identifier] = _scripts(case, run, output)
+ else:
+ start = len(run["commands"])
+ events = []
+ for i, command in enumerate(commands(identifier)):
+ path = output / f"{identifier}-{i}-events.jsonl"
+ observed = _command(
+ run, output, f"{identifier}-{i}", command, 1200, events=path
+ )
+ if path.exists():
+ events.extend(read_events(path))
+ if observed.returncode or not observed.cleanup:
+ break
+ results[identifier] = gate_result(case, run["commands"][start:], events)
+ if results[identifier]["status"] != "PASS":
+ raise RuntimeError(f"{identifier} failed; later cases remain NOT RUN")
+ native = [c for c in cases if c["case_id"] in NATIVE]
+ security = [c for c in cases if c["case_id"] in SECURITY]
+ kinds = {c["peer_kind"] for c in native + security}
+ if native or security:
+ kinds.add("M")
+ if any(c["peer_kind"] == "XR" for c in security):
+ kinds.add("Caddy")
+ supplied = prepare_peers(output, kinds)
+ try:
+ if native:
+ jobs = {}
+ for case in native:
+ identifier = case["case_id"]
+ variant, test = NATIVE[identifier]
+ jobs.setdefault(variant, []).append(dict(case_id=identifier, test=test))
+ directory = output / "native"
+ # Exercise native-gap transports before the long Mihomo matrix.
+ # Ordering changes neither the frozen case set nor its evidence.
+ ordered = sorted(
+ jobs, key=lambda name: (not name.startswith(("h3-", "outer-")), name)
+ )
+ fields_run(directory, ordered, jobs=jobs, supplied=supplied)
+ report = read_json(directory / "xhttp-fields-results.json")
+ for result in native_results(native, report, directory, allow_partial=True):
+ results[result["case_id"]] = result
+ if report["status"] != "PASS":
+ raise RuntimeError("native XHTTP cases failed")
+ if security:
+ directory = output / "security"
+ security_run(
+ directory, [SECURITY[c["case_id"]] for c in security], supplied=supplied
+ )
+ report = read_json(directory / "xhttp-security-results.json")
+ for result in security_results(
+ security, report, directory, allow_partial=True
+ ):
+ results[result["case_id"]] = result
+ if report["status"] != "PASS":
+ raise RuntimeError("native XHTTP security failed")
+ finally:
+ (output / "peers.json").write_text(
+ json.dumps({k: identity for k, (_, identity) in supplied.items()}, indent=2)
+ + "\n"
+ )
+ (output / "fields.json").write_text(
+ json.dumps(fields_report(cases, list(results.values())), indent=2) + "\n"
+ )
+
+
+def required_command_names():
+ return {
+ f"{identifier}-{i}"
+ for identifier in GATES
+ for i in range(len(commands(identifier)))
+ } | {
+ "production-build",
+ "offline-scripts",
+ "feature-default",
+ "feature-minimal",
+ "feature-outbound-vless",
+ *(
+ "feature-" + name
+ for name in (
+ "outbound-trojan",
+ "outbound-vmess",
+ "outbound-hysteria2",
+ "stream-transport",
+ "quic-transport",
+ )
+ ),
+ }
+
+
+def check(run_dir, cases, run, results, peers, paths):
+ from .protocol_harness import SCRIPT_OBSERVATIONS
+
+ needed = {
+ "native/xhttp-fields-results.json",
+ "security/xhttp-security-results.json",
+ "fields.json",
+ "script-tests.json",
+ "resources.jsonl",
+ "peers.json",
+ "cases.json",
+ "summary.md",
+ }
+ if not needed <= set(paths) or cases != definitions():
+ raise ValueError("missing XHTTP artifacts or altered frozen metadata")
+ recalculated = []
+ source_keys = (
+ "parent_commit",
+ "source_tree_sha256",
+ "dirty_patch_sha256",
+ "lock_sha256",
+ )
+ for name, file, evaluator, wanted in (
+ ("native", "xhttp-fields-results.json", native_results, NATIVE),
+ ("security", "xhttp-security-results.json", security_results, SECURITY),
+ ):
+ report = read_json(run_dir / name / file)
+ if (
+ report.get("source") != {key: run.get(key) for key in source_keys}
+ or report.get("status") != "PASS"
+ ):
+ raise ValueError("XHTTP native source identity mismatch")
+ isolation = report.get("isolation", {})
+ if (
+ isolation.get("host_servers") is not False
+ or isolation.get("network_mode") != "hostOnly"
+ or not isolation.get("peers")
+ or any(
+ p.get("joined") is not True or p.get("started") is not True
+ for p in isolation["peers"]
+ )
+ ):
+ raise ValueError("XHTTP native isolation or cleanup missing")
+ if any(
+ identity != peers.get(kind)
+ for kind, identity in report.get("peers", {}).items()
+ ):
+ raise ValueError("XHTTP peer identity changed between reports")
+ recalculated += evaluator(
+ [c for c in cases if c["case_id"] in wanted], report, run_dir / name
+ )
+ if set(peers) != {"M", "XR", "V2", "Caddy"}:
+ raise ValueError("XHTTP required official peers missing")
+ for kind, peer in peers.items():
+ project = {
+ "M": "MetaCubeX/mihomo",
+ "XR": "XTLS/Xray-core",
+ "V2": "v2fly/v2ray-core",
+ "Caddy": "caddyserver/caddy",
+ }[kind]
+ if (
+ peer.get("target") != "linux-arm64"
+ or not peer.get("version")
+ or not peer.get("source_url", "").startswith(
+ f"https://github.com/{project}/releases/"
+ )
+ or not HEX.fullmatch(peer.get("binary_sha256", ""))
+ ):
+ raise ValueError("invalid official XHTTP peer identity")
+ if kind != "Caddy" and not HEX.fullmatch(peer.get("archive_sha256", "")):
+ raise ValueError("missing native download digest")
+ if kind == "Caddy" and (
+ peer.get("source_built") is not True
+ or peer.get("build_cleanup") is not True
+ or peer.get("extra_plugins") != []
+ or set(peer.get("inputs", {})) != {"go.mod", "go.sum", "main.go"}
+ or any(not HEX.fullmatch(value) for value in peer["inputs"].values())
+ ):
+ raise ValueError("gateway is outside the approved xcaddy build exception")
+ records = run.get("commands", [])
+ if (
+ len(records) != len(required_command_names())
+ or {r.get("name") for r in records} != required_command_names()
+ or any(
+ r.get("exit_code") != 0
+ or r.get("cleanup") is not True
+ or r.get("log") not in paths
+ for r in records
+ )
+ ):
+ raise ValueError("missing, duplicate or failed XHTTP command")
+ for case in cases:
+ identifier = case["case_id"]
+ expected_commands = commands(identifier)
+ if not expected_commands:
+ continue
+ selected, events = [], []
+ for i, argv in enumerate(expected_commands):
+ record = next(r for r in records if r["name"] == f"{identifier}-{i}")
+ if record["command"] != [redact(part) for part in argv]:
+ raise ValueError("XHTTP validation command changed")
+ selected.append(record)
+ path = run_dir / f"{identifier}-{i}-events.jsonl"
+ if path.exists():
+ events.extend(read_events(path))
+ recalculated.append(gate_result(case, selected, events))
+ actual = {r["case_id"]: r for r in results}
+ if any(r != actual.get(r["case_id"]) for r in recalculated):
+ raise ValueError("XHTTP results disagree with structured evidence")
+ for record in records:
+ name = record["name"]
+ if name == "feature-default":
+ argv = ["cargo", "test", "--locked", "--test", "feature_foundations"]
+ elif name.startswith("feature-"):
+ argv = ["cargo", "check", "--locked", "--no-default-features", "--lib"]
+ if name != "feature-minimal":
+ argv += ["--features", name.removeprefix("feature-")]
+ elif name == "production-build":
+ argv = [
+ "cargo",
+ "build",
+ "--locked",
+ "--release",
+ "--no-default-features",
+ "--features",
+ DEFAULT_FEATURES,
+ "--lib",
+ ]
+ elif name == "offline-scripts":
+ argv = [
+ sys.executable,
+ "-m",
+ "vcore_scripts.protocol_script_tests",
+ str(run_dir / "script-tests.json"),
+ ]
+ else:
+ continue
+ if record["command"] != [redact(part) for part in argv]:
+ raise ValueError("XHTTP feature or script command changed")
+ script = read_json(run_dir / "script-tests.json")
+ tests = {t["test"]: t["status"] for t in script["cases"]}
+ required_tests = set(SCRIPT_OBSERVATIONS.values()) | {
+ "test_protocol_xhttp.XhttpAcceptanceTest." + name
+ for name in (
+ "test_frozen_catalog_has_all_rows_modes_and_mux_wires",
+ "test_unknown_duplicate_wrong_suite_and_partial_events_fail",
+ "test_unit_gate_requires_every_frozen_assertion_and_successful_command",
+ "test_native_missing_and_duplicate_records_are_not_success",
+ )
+ }
+ if (
+ len(tests) != script["tests_run"]
+ or not required_tests <= set(tests)
+ or any(v != "PASS" for v in tests.values())
+ ):
+ raise ValueError("XHTTP offline failure-path proof missing")
+ fields = fields_report(cases, results)
+ if read_json(run_dir / "fields.json") != fields or any(
+ f["status"] != "PASS" for f in fields["fields"]
+ ):
+ raise ValueError("incomplete XHTTP field behavior coverage")
+ resources = read_events(run_dir / "resources.jsonl")
+ owned = [
+ e
+ for e in resources
+ if e.get("suite") == "XHTTP-OWNED" and e.get("status") == "PASS"
+ ]
+ if len(owned) != 20 * len(REPRESENTATIVES) or any(
+ not idle_resources(e.get("resources")) for e in owned
+ ):
+ raise ValueError("missing XHTTP twenty-round owned resource proof")
+ print(f"XHTTP: PASS ({len(cases)} required cases; {len(FIELD_IDS)} field rows)")
diff --git a/scripts/src/vcore_scripts/protocol_xhttp_catalog.py b/scripts/src/vcore_scripts/protocol_xhttp_catalog.py
new file mode 100644
index 0000000..a618fa1
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_xhttp_catalog.py
@@ -0,0 +1,394 @@
+"""Frozen XHTTP cases. Independent tuning is pairwise; coupled modes remain explicit."""
+
+from __future__ import annotations
+
+import hashlib
+
+from .protocol_vless_acceptance import OBSERVATIONS as PREVIOUS
+from .protocol_vmess_acceptance import SCRIPT_ASSERTIONS
+from .protocol_xhttp_fields import native_kind, variants
+
+UNIT_TESTS = {
+ "xhttp_config": [
+ "xhttp_fields_reject_wrong_types_null_and_every_range_boundary_before_io",
+ "empty_http_authority_falls_back_to_each_legs_authentication_name",
+ "download_security_changes_do_not_silently_discard_inherited_certificate_policy",
+ "h3_requires_exclusive_alpn_and_standard_tls_on_each_leg",
+ "custom_headers_inherit_replace_clear_and_do_not_leak_values",
+ "conflicting_request_fields_are_rejected_on_both_legs_before_io",
+ "http_version_selects_h1_only_for_its_single_alpn_and_supports_plaintext",
+ "download_certificate_policy_inherits_and_explicit_false_or_empty_clears",
+ "download_mtls_identity_is_inherited_or_replaced_and_cleared_as_a_pair",
+ "download_reality_object_replaces_inherits_or_clears_without_merging_keys",
+ "reuse_object_presence_and_download_whole_object_replacement_are_preserved",
+ ],
+ "sing_mux_config": [
+ "sing_mux_accepts_three_protocols_and_rejects_invalid_or_ignored_options"
+ ],
+ "xhttp_requests": [
+ "packet_up_coalesces_small_writes_and_flushes_without_more_caller_io",
+ "packet_up_backpressures_bounded_batches_and_stop_cancels_the_timer",
+ "first_vless_read_never_acknowledges_or_replays_a_concurrent_packet_write",
+ "response_codes_follow_mihomo_streaming_and_packet_rules",
+ "streaming_content_type_can_be_disabled_without_disabling_padding",
+ "custom_semantic_headers_are_allowed_when_no_generated_field_overwrites_them",
+ "padding_uses_the_configured_http_location_and_encoding",
+ "packet_metadata_and_upload_methods_are_sent_in_each_supported_location",
+ "packet_upload_can_move_payload_into_bounded_header_or_cookie_chunks",
+ "http1_stream_one_is_chunked_duplex_and_shutdown_closes_both_directions",
+ "http1_packet_up_shares_a_session_across_two_connections",
+ "http1_response_body_can_arrive_after_the_response_headers",
+ "custom_request_headers_reach_the_http_peer_without_changing_body",
+ ],
+ "xhttp_reuse": [
+ "enabled_reuse_shares_physical_h2_without_one_close_killing_its_sibling",
+ "reuse_thresholds_expand_and_retire_without_closing_active_sessions",
+ "expired_transport_is_not_assigned_again_while_old_session_stays_live",
+ "pooled_packet_posts_do_not_each_consume_a_transport_lease",
+ "h2_keepalive_uses_default_explicit_and_disabled_idle_periods",
+ "download_uses_its_own_reuse_counters_and_keeps_shared_sessions_alive",
+ "h1_packet_upload_reuses_its_idle_connection_but_reopens_the_cancelled_get",
+ "stopping_during_handshake_prevents_late_driver_admission",
+ "stop_wakes_a_handshake_even_when_the_peer_never_responds",
+ ],
+ "sing_mux": [
+ "yamux_replacing_dropped_streams_at_capacity_keeps_the_sibling_alive",
+ "sing_mux_scheduling_uses_the_selected_branch_not_a_global_stream_quota",
+ "h2mux_sends_idle_ping_and_retires_a_peer_that_never_acknowledges",
+ "only_tcp_preserves_all_three_vless_udp_wire_commands",
+ "h2mux_reuses_physical_vless_and_cancels_only_one_logical_stream",
+ "yamux_reuses_physical_vless_and_cancels_only_one_logical_stream",
+ "smux_reuses_physical_vless_and_cancels_only_one_logical_stream",
+ "sing_mux_udp_preserves_addresses_and_cancellation_safe_partial_frames",
+ ],
+ "xhttp_budget": [
+ "h3_rejects_incapable_or_small_budget_upstreams_before_any_datagram"
+ ],
+}
+
+DRIVER_TESTS = ["malformed_smux_headers_close_the_owned_driver_before_reading_a_body"]
+
+FIELD_IDS = {
+ *(f"X{i:02}" for i in range(1, 30)),
+ *(f"D{i:02}" for i in range(1, 16)),
+ *(f"D{i:02}" for i in range(27, 33)),
+ *(f"M{i:02}" for i in range(1, 8)),
+}
+OBSERVATIONS = {
+ "XHTTP-CFG": UNIT_TESTS["xhttp_config"] + UNIT_TESTS["sing_mux_config"],
+ "XHTTP-UNIT": sum(
+ (
+ UNIT_TESTS[n]
+ for n in ("xhttp_requests", "xhttp_reuse", "sing_mux", "xhttp_budget")
+ ),
+ [],
+ )
+ + DRIVER_TESTS,
+ "XHTTP-REGRESSION": PREVIOUS["VLESS-REGRESSION"]
+ + PREVIOUS["VLESS-CODEC"]
+ + PREVIOUS["VLESS-TRANSPORT"]
+ + PREVIOUS["VLESS-VISION"],
+}
+OBSERVATIONS["XHTTP-RELEASE"] = OBSERVATIONS["XHTTP-CFG"] + OBSERVATIONS["XHTTP-UNIT"]
+GATES = {
+ "XHTTP-CFG",
+ "XHTTP-UNIT",
+ "XHTTP-REGRESSION",
+ "XHTTP-RELEASE",
+ "XHTTP-QUALITY",
+ "XHTTP-FEATURES",
+ "XHTTP-SCRIPTS",
+}
+SECURITY = {f"XHTTP-SECURITY-{v.upper()}": v for v in ("h1", "h2", "h3")}
+NATIVE = {}
+VERSIONS = ("h1", "h2", "h1c", "h2c", "h1r", "h2r", "h3")
+ALL_VARIANTS = variants()
+
+
+def add(variant, suffix, test):
+ if variant not in ALL_VARIANTS:
+ raise ValueError("missing frozen XHTTP variant")
+ # Case-sensitive table names need distinct stable identifiers.
+ digest = hashlib.sha256(variant.encode()).hexdigest()[:8].upper()
+ identifier = f"XHTTP-{variant.upper()}-{suffix}-{digest}"
+ if identifier in NATIVE:
+ raise ValueError("duplicate XHTTP requirement")
+ NATIVE[identifier] = (variant, test)
+
+
+for version in VERSIONS:
+ for mode in ("stream-one", "stream-up", "packet-up"):
+ variant = f"{version}-{mode}-headers"
+ add(variant, "BASE", "public_base")
+ add(variant, "CLOSE", "close::native_mihomo_xhttp_close")
+ for mode in ("stream-up", "packet-up"):
+ variant = f"{version}-{mode}-split-reuse"
+ add(variant, "BASE", "public_base")
+ add(variant, "CLOSE", "close::native_mihomo_xhttp_close")
+ for suffix in ("auto", "auto-download"):
+ add(f"{version}-{suffix}", "AUTO", "native_xhttp_request_fields")
+ if version.endswith("r"):
+ for suffix in (
+ "download-reality-replacement",
+ "reject-download-short-id",
+ "reject-download-public-key",
+ ):
+ add(
+ f"{version}-{suffix}",
+ "SECURITY",
+ "security::native_xhttp_security"
+ if suffix.startswith("reject")
+ else "native_xhttp_request_fields",
+ )
+
+# Every finite request enum is consumed on H1, H2 and H3. Security is orthogonal
+# here; every plain/TLS/REALITY + mode + download branch has a public BASE above.
+for version in ("h1", "h2", "h3"):
+ for name, (options, v) in ALL_VARIANTS.items():
+ if v != version or "_mux" in options or "_keepalive" in options:
+ continue
+ suffix = name.removeprefix(version + "-")
+ if suffix.startswith(
+ ("padding-", "metadata-", "payload-", "session-", "post-", "reject-")
+ ) or suffix in (
+ "stream-up-no-grpc",
+ "stream-one-no-grpc",
+ "body-auto",
+ ):
+ add(
+ name,
+ "FIELDS",
+ "security::native_xhttp_security"
+ if options.get("_reject")
+ else "native_xhttp_request_fields",
+ )
+add(
+ "h3-keepalive",
+ "KEEPALIVE",
+ "keepalive::native_h3_keepalive_observes_each_leg_and_stop",
+)
+
+# All three wire protocols and both only-tcp branches for every outer transport.
+# Padding parity alternates between branches; H2 additionally expands all padding
+# values. Padding and the outer framing are independent, tested separately above.
+for outer in (
+ *VERSIONS,
+ *(
+ f"outer-{m}"
+ for m in (
+ "tcp",
+ "tcp-tls",
+ "tcp-reality",
+ "ws",
+ "ws-tls",
+ "ws-reality",
+ "grpc",
+ "grpc-tls",
+ "grpc-reality",
+ "http",
+ "http-tls",
+ "h2",
+ "h2-tls",
+ "ws-header",
+ "ws-header-tls",
+ "ws-path",
+ "ws-path-tls",
+ )
+ ),
+):
+ for index, protocol in enumerate(("h2mux", "smux", "yamux")):
+ for only in (False, True):
+ paddings = (
+ (False, True) if outer == "h2" else ((index + int(only)) % 2 == 0,)
+ )
+ for padding in paddings:
+ variant = (
+ f"{outer}-mux-{protocol}-{'padded' if padding else 'plain'}"
+ + ("-only-tcp" if only else "")
+ )
+ add(variant, "BASE", "public_base")
+
+for version in ("h1", "h2", "h3"):
+ for protocol in ("h2mux", "smux", "yamux"):
+ add(
+ f"{version}-mux-{protocol}-padding-required",
+ "REJECT",
+ "security::native_xhttp_security",
+ )
+
+REPRESENTATIVES = (
+ "h1-packet-up-split-reuse",
+ "h2-stream-up-split-reuse",
+ "h3-packet-up-split-reuse",
+ "h2-mux-h2mux-padded",
+ "h2-mux-smux-padded",
+ "h2-mux-yamux-padded",
+)
+for variant in REPRESENTATIVES:
+ for suffix, test in (
+ ("GRAPH", "runtime::public_graph"),
+ ("IPV6", "runtime::public_ipv6_and_gates"),
+ ("ENTRYPOINTS", "runtime::public_entrypoints"),
+ ("LIFE", "runtime::public_lifecycle"),
+ ("ISOLATION", "runtime::public_udp_isolation"),
+ ("OWNED", "lifecycle::native_xhttp_owned_resources"),
+ ("NEG", "public_negative"),
+ ):
+ add(variant, suffix, test)
+for variant in (
+ "h1-packet-up-reuse",
+ "h2-stream-up-reuse",
+ "h3-packet-up-reuse",
+ "h2-mux-h2mux-padded",
+ "h2-mux-smux-padded",
+ "h2-mux-yamux-padded",
+):
+ add(
+ variant,
+ "POOL-SELECTION",
+ "runtime::grpc_pool_keeps_physical_selection_until_new_transport",
+ )
+
+X_NAMES = (
+ "path",
+ "host",
+ "mode",
+ "headers",
+ "no-grpc-header",
+ "x-padding-bytes",
+ "x-padding-obfs-mode",
+ "x-padding-key",
+ "x-padding-header",
+ "x-padding-placement",
+ "x-padding-method",
+ "uplink-http-method",
+ "session-placement",
+ "session-key",
+ "session-table",
+ "session-length",
+ "seq-placement",
+ "seq-key",
+ "uplink-data-placement",
+ "uplink-data-key",
+ "uplink-chunk-size",
+ "sc-max-each-post-bytes",
+ "sc-min-posts-interval-ms",
+)
+REUSE_ROWS = {
+ *(f"X{i:02}" for i in range(24, 30)),
+ *(f"D{i:02}" for i in range(27, 33)),
+}
+
+
+def rows(identifier):
+ if identifier in {"XHTTP-CFG", "XHTTP-UNIT"}:
+ return sorted(FIELD_IDS)
+ if identifier in GATES:
+ return []
+ if identifier in SECURITY:
+ return [f"D{i:02}" for i in range(1, 14)]
+ variant, test = NATIVE[identifier]
+ options, version = ALL_VARIANTS[variant]
+ if version.startswith("outer-"):
+ return [f"M{i:02}" for i in range(1, 8)]
+ result = {"X01", "X02", "X03", "X06"}
+ result |= {f"X{i:02}" for i, name in enumerate(X_NAMES, 1) if name in options}
+ if "download-settings" in options:
+ result |= {"D01", "D02", "D03", "D04", "D05", "D06", "D07", "D08"}
+ if version.endswith("r"):
+ result |= {"D14", "D15"}
+ if "reuse-settings" in options or "reuse" in variant:
+ result |= REUSE_ROWS
+ if "_mux" in options:
+ result |= {f"M{i:02}" for i in range(1, 8)}
+ if options.get("_keepalive"):
+ result |= {"X29", "D32"}
+ return sorted(result)
+
+
+def definitions():
+ result = []
+ for identifier in sorted(GATES | set(SECURITY) | set(NATIVE)):
+ variant, test = NATIVE.get(
+ identifier, (SECURITY.get(identifier, "memory-or-build"), identifier)
+ )
+ options, version = ALL_VARIANTS.get(variant, ({}, variant))
+ native = identifier not in GATES
+ kind = native_kind(version) if native else "unit"
+ if identifier in SECURITY:
+ kind = "XR" if version == "h3" else "M"
+ encrypted = not version.endswith("c") and (
+ not version.startswith("outer-") or version.endswith(("-tls", "-reality"))
+ )
+ gap = (
+ {
+ "reason": "Xray H3 forwards to the official Mihomo VLESS decoder "
+ "for packetaddr/sing-mux. mTLS uses the approved unmodified "
+ "xcaddy/Caddy gateway to one Xray handler.",
+ "source": "https://github.com/XTLS/Xray-core/tree/v26.3.27/transport/internet/splithttp",
+ }
+ if kind == "XR"
+ else {
+ "reason": "Official V2Ray supplies HTTP/H2/custom-ED framing; "
+ "sing-mux is decoded by official Mihomo, not V2Ray CommandMux.",
+ "source": "https://github.com/MetaCubeX/mihomo/blob/v1.19.31/listener/inbound/vless.go",
+ }
+ if kind == "V2"
+ else None
+ )
+ result.append(
+ dict(
+ case_id=identifier,
+ stage="XHTTP",
+ substage="XHTTP.http3"
+ if version == "h3"
+ else "XHTTP.mux"
+ if "_mux" in options
+ else "XHTTP.download"
+ if identifier in SECURITY or "download-settings" in options
+ else "XHTTP.requests"
+ if native
+ else "XHTTP.acceptance",
+ required=True,
+ row_ids=rows(identifier),
+ protocol="vless",
+ network=variant,
+ security="tls-or-reality" if encrypted else "plain",
+ udp_codec="raw/xudp/packetaddr/sing-mux",
+ field_values=dict(
+ scope="protocol-consumer", variant=variant, **options
+ ),
+ outer_family="IPv4/IPv6",
+ inner_family="IPv4/IPv6/domain",
+ target_type="isolated synthetic origin"
+ if native
+ else "memory-only/build",
+ upstream_graph="direct/concrete/nested-select"
+ if "graph" in test
+ else "per-assertion",
+ peer_kind=kind,
+ peer_config=dict(variant=variant, test=test),
+ gap_source=gap,
+ expected_observation=OBSERVATIONS.get(
+ identifier,
+ SCRIPT_ASSERTIONS if identifier == "XHTTP-SCRIPTS" else [test],
+ ),
+ required_evidence=["structured-assertions", "command", "cleanup"]
+ + (["official-peer-identity", "isolated-origins"] if native else []),
+ prerequisites=[
+ "owned-host-only-container-network",
+ "official-latest-peer",
+ ]
+ if native
+ else ["rust-toolchain"],
+ runner="native-xhttp"
+ if identifier in NATIVE
+ else "xhttp-security"
+ if identifier in SECURITY
+ else "xhttp-gate",
+ timeout_seconds=3600
+ if identifier in GATES or identifier in SECURITY
+ else 300,
+ )
+ )
+ return result
diff --git a/scripts/src/vcore_scripts/protocol_xhttp_fields.py b/scripts/src/vcore_scripts/protocol_xhttp_fields.py
new file mode 100644
index 0000000..a9fb4d2
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_xhttp_fields.py
@@ -0,0 +1,1334 @@
+"""XHTTP request-field development checks, not the complete XHTTP stage gate."""
+
+from __future__ import annotations
+
+import contextlib
+import copy
+import json
+import os
+import shutil
+import ssl
+import tempfile
+from pathlib import Path
+
+from .builds import CORE_DIR
+from .caddy_build import build_caddy
+from .mihomo_isolation import exclusive_run
+from .mihomo_release import download_mihomo
+from .native_release import download_native
+from .protocol_containers import ContainerLab, command
+from .protocol_evidence import idle_resources, read_events
+from .protocol_fixtures import certificate_chain, certificates
+from .protocol_inputs import redact, source_identity
+from .protocol_peers import run_command
+from .protocol_vless_container import CLIENT_FINGERPRINTS
+from .protocol_vless_peers import (
+ configuration as vless_configuration,
+)
+from .protocol_vless_peers import (
+ peer_kind as vless_peer_kind,
+)
+from .protocol_vless_public import events_pass as vless_events_pass
+from .protocol_vless_security import client_identities
+from .protocol_xhttp_gateway import gateway_config, sanitized_gateway_log
+from .protocol_xhttp_peers import CLIENT_ID, peer_config
+
+PUBLIC_TESTS = (
+ "public_base",
+ "public_negative",
+ "runtime::public_entrypoints",
+ "runtime::public_graph",
+ "runtime::public_ipv6_and_gates",
+ "runtime::public_lifecycle",
+ "runtime::public_udp_isolation",
+ "runtime::grpc_pool_keeps_physical_selection_until_new_transport",
+)
+
+
+def native_kind(version):
+ return (
+ vless_peer_kind(version.removeprefix("outer-"))
+ if version.startswith("outer-")
+ else "XR"
+ if version == "h3"
+ else "M"
+ )
+
+
+def public_events_pass(events, assertion):
+ if assertion not in PUBLIC_TESTS or any(
+ e.get("suite") not in {"XHTTP-PUBLIC", "XHTTP-BASE", "XHTTP-LIFE"}
+ for e in events
+ ):
+ return False
+ expected = {
+ ("XHTTP-PUBLIC", assertion): 1,
+ }
+ if assertion == "public_base":
+ expected.update(
+ {
+ ("XHTTP-BASE", "tcp_10mib_both_directions"): 3,
+ ("XHTTP-BASE", "udp_each_codec_and_family"): 3,
+ }
+ )
+ if assertion == "runtime::public_lifecycle":
+ expected[("XHTTP-LIFE", "stop_and_remain_quiet")] = 20
+ if len(events) != 2 * sum(expected.values()):
+ return False
+ for key, count in expected.items():
+ matched = [e for e in events if (e.get("suite"), e.get("assertion")) == key]
+ if [e.get("status") for e in matched] != ["BEGIN", "PASS"] * count:
+ return False
+ remapped = [
+ dict(e, suite=e["suite"].replace("XHTTP-", "VLESS-", 1)) for e in events
+ ]
+ return vless_events_pass(remapped, assertion, "xhttp")
+
+
+def variants():
+ result = {}
+ result["auto"] = {"mode": "auto"}
+ result["auto-download"] = {"mode": "auto", "download-settings": {}}
+ for fault, peer_overrides in {
+ "session": {"session-placement": "header", "session-key": "X-Required-Session"},
+ "sequence": {"seq-placement": "header", "seq-key": "X-Required-Sequence"},
+ "payload": {
+ "uplink-data-placement": "header",
+ "uplink-data-key": "required-data",
+ },
+ "post-size": {"sc-max-each-post-bytes": "1"},
+ }.items():
+ result[f"reject-{fault}"] = {
+ "mode": "packet-up",
+ "_reject": True,
+ "_server": peer_overrides,
+ }
+ result["post-minimum"] = {
+ "mode": "packet-up",
+ "sc-max-each-post-bytes": "1",
+ "sc-min-posts-interval-ms": "1",
+ "_tiny": True,
+ }
+ result["post-maximum"] = {
+ "mode": "packet-up",
+ "sc-max-each-post-bytes": "16777216",
+ "sc-min-posts-interval-ms": "0-1",
+ }
+ for table in (
+ "uuid",
+ "ALPHABET",
+ "Alphabet",
+ "BASE36",
+ "Base62",
+ "HEX",
+ "alphabet",
+ "base36",
+ "hex",
+ "number",
+ "abAB0123",
+ ):
+ result[f"session-{table}"] = {
+ "mode": "packet-up",
+ "session-table": table,
+ "sc-min-posts-interval-ms": "1",
+ "_tiny": True,
+ }
+ for mode in ("stream-one", "stream-up", "packet-up"):
+ result[f"{mode}-headers"] = dict(mode=mode, headers={"X-Probe": "fixture"})
+ result["stream-up-no-grpc"] = {"mode": "stream-up", "no-grpc-header": True}
+ result["stream-one-no-grpc"] = {"mode": "stream-one", "no-grpc-header": True}
+ result["body-auto"] = {
+ "mode": "packet-up",
+ "uplink-data-placement": "auto",
+ "sc-min-posts-interval-ms": "1",
+ }
+ for protocol in ("h2mux", "smux", "yamux"):
+ for padding in (False, True):
+ result[f"mux-{protocol}-{'padded' if padding else 'plain'}"] = {
+ "mode": "packet-up",
+ "sc-min-posts-interval-ms": "1",
+ "_mux": {
+ "enabled": True,
+ "protocol": protocol,
+ "padding": padding,
+ "max-connections": 1,
+ },
+ }
+ for mode in ("stream-one", "stream-up", "packet-up"):
+ result[f"{mode}-reuse"] = {"mode": mode, "reuse-settings": {}}
+ if mode == "packet-up":
+ result[f"{mode}-reuse"]["sc-min-posts-interval-ms"] = "1"
+ for mode in ("stream-up", "packet-up"):
+ result[f"{mode}-split-reuse"] = {
+ "mode": mode,
+ "reuse-settings": {"h-max-request-times": "1"},
+ "download-settings": {
+ "alpn": ["http/1.1"],
+ "headers": {"X-Down": "fixture"},
+ "reuse-settings": {},
+ },
+ }
+ if mode == "packet-up":
+ result[f"{mode}-split-reuse"]["sc-min-posts-interval-ms"] = "1"
+ for placement in ("queryInHeader", "header", "query", "cookie"):
+ for method in ("repeat-x", "tokenish"):
+ options = {
+ "mode": "packet-up",
+ "x-padding-bytes": "100",
+ "x-padding-obfs-mode": True,
+ "x-padding-placement": placement,
+ "x-padding-method": method,
+ "sc-min-posts-interval-ms": "1",
+ }
+ if placement != "header":
+ options["x-padding-key"] = "pad"
+ if placement in ("queryInHeader", "header"):
+ options["x-padding-header"] = "X-Pad"
+ result[f"padding-{placement}-{method}"] = options
+ for placement, method in zip(
+ ("path", "query", "header", "cookie"),
+ ("POST", "PUT", "PATCH", "DELETE"),
+ strict=True,
+ ):
+ options = {
+ "mode": "packet-up",
+ "session-placement": placement,
+ "seq-placement": placement,
+ "uplink-http-method": method,
+ "session-table": "number",
+ "session-length": "10",
+ "sc-min-posts-interval-ms": "1",
+ }
+ if placement != "path":
+ options.update({"session-key": "sid", "seq-key": "seq"})
+ result[f"metadata-{placement}-{method}"] = options
+ for placement in ("header", "cookie"):
+ result[f"payload-{placement}"] = {
+ "mode": "packet-up",
+ "uplink-data-placement": placement,
+ "uplink-data-key": "data",
+ "uplink-chunk-size": "64-128",
+ "sc-min-posts-interval-ms": "1",
+ }
+ result[f"payload-{placement}-auto"] = dict(
+ result[f"payload-{placement}"], **{"uplink-chunk-size": "0"}
+ )
+ for protocol in ("h2mux", "smux", "yamux"):
+ result[f"mux-{protocol}-padding-required"] = {
+ "mode": "stream-one",
+ "_mux": {"enabled": True, "protocol": protocol, "padding": False},
+ "_require-padding": True,
+ "_reject": True,
+ }
+ expanded = {}
+ for version in ("h2", "h1", "h2c", "h1c", "h3", "h2r", "h1r"):
+ for name, fields in result.items():
+ options = copy.deepcopy(fields)
+ if version == "h3" and "download-settings" in options:
+ options["download-settings"]["alpn"] = ["h3"]
+ expanded[f"{version}-{name}"] = (options, version)
+ if "_mux" in options:
+ tcp_only = copy.deepcopy(options)
+ tcp_only["_mux"]["only-tcp"] = True
+ expanded[f"{version}-{name}-only-tcp"] = (tcp_only, version)
+ if version == "h3":
+ expanded["h3-keepalive"] = (
+ {"mode": "packet-up", "_keepalive": True},
+ version,
+ )
+ if version.endswith("r"):
+ from .mihomo_extended import PUBLIC_KEY
+
+ replacement = {"public-key": PUBLIC_KEY}
+ expanded[f"{version}-download-reality-replacement"] = (
+ {
+ "mode": "stream-up",
+ "download-settings": {"reality-opts": replacement},
+ },
+ version,
+ )
+ expanded[f"{version}-reject-download-short-id"] = (
+ {
+ "mode": "stream-up",
+ "download-settings": {
+ "reality-opts": dict(replacement, **{"short-id": "ff"})
+ },
+ "_reject": True,
+ },
+ version,
+ )
+ expanded[f"{version}-reject-download-public-key"] = (
+ {
+ "mode": "stream-up",
+ "download-settings": {
+ "reality-opts": {
+ # Valid X25519 encoding, not this server's public key.
+ "public-key": "CQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+ }
+ },
+ "_reject": True,
+ },
+ version,
+ )
+ for mode in (
+ "tcp",
+ "tcp-tls",
+ "tcp-reality",
+ "ws",
+ "ws-tls",
+ "ws-reality",
+ "grpc",
+ "grpc-tls",
+ "grpc-reality",
+ "http",
+ "http-tls",
+ "h2",
+ "h2-tls",
+ "ws-header",
+ "ws-header-tls",
+ "ws-path",
+ "ws-path-tls",
+ ):
+ for name, options in result.items():
+ if "_mux" in options:
+ expanded[f"outer-{mode}-{name}"] = (
+ copy.deepcopy(options),
+ "outer-" + mode,
+ )
+ tcp_only = copy.deepcopy(options)
+ tcp_only["_mux"]["only-tcp"] = True
+ expanded[f"outer-{mode}-{name}-only-tcp"] = (tcp_only, "outer-" + mode)
+ return expanded
+
+
+def server_fields(fields, kind):
+ if kind == "M":
+ return fields
+ names = {
+ "path": "path",
+ "mode": "mode",
+ "host": "host",
+ "no-grpc-header": "noGRPCHeader",
+ "x-padding-bytes": "xPaddingBytes",
+ "x-padding-obfs-mode": "xPaddingObfsMode",
+ "x-padding-key": "xPaddingKey",
+ "x-padding-header": "xPaddingHeader",
+ "x-padding-placement": "xPaddingPlacement",
+ "x-padding-method": "xPaddingMethod",
+ "uplink-http-method": "uplinkHTTPMethod",
+ "session-placement": "sessionPlacement",
+ "session-key": "sessionKey",
+ "seq-placement": "seqPlacement",
+ "seq-key": "seqKey",
+ "uplink-data-placement": "uplinkDataPlacement",
+ "uplink-data-key": "uplinkDataKey",
+ "uplink-chunk-size": "uplinkChunkSize",
+ "sc-max-each-post-bytes": "scMaxEachPostBytes",
+ }
+ if not fields.keys() <= names.keys():
+ raise ValueError("missing explicit Xray field translation")
+ return {names[key]: value for key, value in fields.items()}
+
+
+def events_pass(events, assertion, *, owned=False):
+ if any(e.get("schema_version") != 1 for e in events):
+ return False
+ main = [event for event in events if event.get("suite") == "XHTTP-XHTTP"]
+ if (
+ len(main) != 2
+ or [e.get("status") for e in main] != ["BEGIN", "PASS"]
+ or any(e.get("assertion") != assertion for e in main)
+ ):
+ return False
+ if not owned:
+ return len(events) == 2
+ cycles = [e for e in events if e.get("suite") == "XHTTP-OWNED"]
+ if len(events) != 42 or len(cycles) != 40:
+ return False
+ for start, finish in zip(cycles[::2], cycles[1::2], strict=True):
+ if (
+ start.get("status") != "BEGIN"
+ or start.get("assertion") != "stop_and_remain_quiet"
+ or finish.get("status") != "PASS"
+ or finish.get("assertion") != "stop_and_remain_quiet"
+ or finish.get("seconds", 0) < 5
+ or not idle_resources(finish.get("resources"))
+ ):
+ return False
+ points = finish.get("checkpoints", [])
+ if len(points) != 3 or [p.get("phase") for p in points] != [
+ "baseline",
+ "after-stop",
+ "quiet",
+ ]:
+ return False
+ if not all(idle_resources(p.get("resources")) for p in points):
+ return False
+ if points[1]["resources"] != points[2]["resources"]:
+ return False
+ return True
+
+
+def close_reference(lab, stack, root, name, node, origin, binary, output):
+ comparison_dir = root / "comparison"
+ comparison_dir.mkdir()
+ shutil.copy2(binary, comparison_dir / "peer")
+ reference = copy.deepcopy(node)
+ reference["name"] = "reference"
+ reference.pop("smux", None)
+ if reference.get("reality-opts"):
+ # Required by the official Mihomo client's uTLS REALITY backend. This
+ # belongs only to the reference fixture, not VCore's public config.
+ reference["client-fingerprint"] = "chrome"
+ config = {
+ "socks-port": 23002,
+ "allow-lan": True,
+ "bind-address": "*",
+ "log-level": "warning",
+ "ipv6": True,
+ "proxies": [reference],
+ "rules": ["MATCH,reference"],
+ }
+ (comparison_dir / "config.json").write_text(json.dumps(config))
+ comparison = lab.start(
+ stack,
+ comparison_dir,
+ name + "-comparison",
+ ["/data/fixture/peer", "-d", "/data", "-f", "/data/fixture/config.json"],
+ )
+ comparison.release()
+ comparison.wait_tcp(23002)
+ result = run_command(
+ [
+ "container",
+ "exec",
+ origin.name,
+ "env",
+ "VCORE_ISOLATED_ORIGIN=1",
+ "python",
+ "-B",
+ "/data/fixture/close.py",
+ comparison.ipv4,
+ origin.ipv4,
+ ],
+ timeout=30,
+ )
+ (output / f"{name}-close-command.log").write_text(
+ redact(result.stdout.decode(errors="replace"))
+ )
+ (output / f"{name}-comparison.log").write_text(
+ redact(command("logs", comparison.name)[-65536:])
+ )
+ if result.returncode or not result.cleanup:
+ raise RuntimeError("official XHTTP close comparison failed")
+ observed = json.loads(result.stdout)
+ observed["scope"] = "same-mode"
+ (output / f"{name}-close-reference.json").write_text(json.dumps(observed) + "\n")
+ comparison.ensure_alive()
+ return observed
+
+
+def selected_profile_variants(profile):
+ """Named-profile download-leg crossings; ordinary XHTTP variants are unchanged."""
+ other = "firefox" if profile in {"chrome", "chrome120"} else "chrome"
+ result = {}
+ for label, override in (
+ ("inherit", {}),
+ ("different", {"client-fingerprint": other}),
+ ("clear", {"client-fingerprint": "none"}),
+ ("reject-pin", {"client-fingerprint": other, "fingerprint": "11" * 32}),
+ ):
+ options = {
+ "mode": "stream-up",
+ "reuse-settings": {},
+ "download-settings": {
+ "alpn": ["http/1.1"],
+ "reuse-settings": {},
+ **override,
+ },
+ }
+ if label == "reject-pin":
+ options["_reject"] = True
+ result[f"h2-selected-download-{label}"] = (options, "h2")
+ result["h3-selected-download-clear"] = (
+ {
+ "mode": "stream-up",
+ "_main_alpn": "h2",
+ "download-settings": {"alpn": ["h3"], "client-fingerprint": "none"},
+ },
+ "h3",
+ )
+ return result
+
+
+def selected_gateway_config(upstream):
+ """Both HTTP versions reach one native XHTTP session table, with real mTLS."""
+ config = gateway_config(upstream)
+ config["apps"]["http"]["servers"]["fixture"]["protocols"] = ["h2", "h3"]
+ return config
+
+
+def run(
+ output: Path,
+ selected: list[str],
+ *,
+ udp: bool = False,
+ owned: bool = False,
+ public: str | None = None,
+ jobs: dict | None = None,
+ supplied: dict | None = None,
+ client_fingerprint: str | None = None,
+ encryption: str | None = None,
+ ech: bool = False,
+ jls: bool = False,
+):
+ if ech and jls:
+ raise ValueError("ECH and JLS are mutually exclusive")
+ if client_fingerprint is not None and client_fingerprint not in CLIENT_FINGERPRINTS:
+ raise ValueError("unsupported named client profile")
+ if public is not None and (public not in PUBLIC_TESTS or udp or owned):
+ raise ValueError("invalid public consumer selection")
+ cases = variants()
+ if ech:
+ from .protocol_ech import field_variants
+
+ cases.update(field_variants())
+ if encryption is not None:
+ from .protocol_encryption import cases as encryption_profiles
+
+ if encryption not in encryption_profiles():
+ raise ValueError("unsupported Encryption fixture")
+ if encryption is not None or ech:
+ # Official V2Ray terminates only the legacy transport. A separate
+ # official Mihomo handler authenticates Encryption and decodes VLESS.
+ for mode in ("http", "h2", "ws-header", "ws-path"):
+ for suffix in ("", "-tls"):
+ name = f"outer-{mode}{suffix}"
+ cases[name] = ({}, name)
+ if client_fingerprint:
+ cases.update(selected_profile_variants(client_fingerprint))
+ if jobs is not None:
+ if set(jobs) != set(selected) or any(not entries for entries in jobs.values()):
+ raise ValueError("invalid frozen native jobs")
+ allowed = set(PUBLIC_TESTS) | {
+ "native_xhttp_request_fields",
+ "native_xhttp_udp_encodings",
+ "lifecycle::native_xhttp_owned_resources",
+ "keepalive::native_h3_keepalive_observes_each_leg_and_stop",
+ "security::native_xhttp_security",
+ "close::native_mihomo_xhttp_close",
+ }
+ ids = [entry["case_id"] for entries in jobs.values() for entry in entries]
+ if len(ids) != len(set(ids)) or any(
+ entry["test"] not in allowed
+ for entries in jobs.values()
+ for entry in entries
+ ):
+ raise ValueError("unknown or duplicate frozen native job")
+ if not selected:
+ selected = list(cases)
+ if len(selected) != len(set(selected)) or not set(selected) <= cases.keys():
+ raise ValueError("invalid XHTTP field case selection")
+ if ech and any(
+ (
+ cases[name][1] not in {"h1", "h2", "h3"}
+ and not (
+ cases[name][1].startswith("outer-") and cases[name][1].endswith("-tls")
+ )
+ )
+ or "_main_alpn" in cases[name][0]
+ for name in selected
+ ):
+ raise ValueError("static ECH requires a native standard TLS peer")
+ if jls and any(cases[name][1] not in {"h1", "h2"} for name in selected):
+ raise ValueError("JLS field gate requires a Mihomo stream TLS peer")
+ if client_fingerprint is not None:
+ for name in selected:
+ options, version = cases[name]
+ if version.startswith("outer-") or version.endswith("c"):
+ raise ValueError("profile field requires a TLS XHTTP node")
+ if (
+ client_fingerprint != "none"
+ and version == "h3"
+ and "_main_alpn" not in options
+ ):
+ raise ValueError("named client profiles require stream TLS")
+ if (
+ not output.is_relative_to(CORE_DIR / "target/interop/runs")
+ or output == CORE_DIR / "target/interop/runs"
+ ):
+ raise ValueError("new run directory must be directly under target/interop/runs")
+ output.mkdir(exist_ok=False)
+ report = dict(
+ stage="SECURITY.ech"
+ if ech
+ else "SECURITY.encryption"
+ if encryption
+ else "XHTTP",
+ ech=ech,
+ jls=jls,
+ encryption_profile=encryption,
+ client_fingerprint=client_fingerprint,
+ scope="protocol-consumer"
+ if jobs is not None
+ else "request-fields-development-only",
+ traffic=public
+ or ("owned-resources" if owned else "udp-three-encodings" if udp else "tcp"),
+ source=source_identity(),
+ status="NOT RUN",
+ cases=[],
+ peers={},
+ isolation={},
+ )
+ try:
+ artifacts = {}
+ if any("_main_alpn" in cases[name][0] for name in selected):
+ gateway_artifact = build_caddy(output / "Caddy")
+ artifacts["Caddy"] = gateway_artifact.binary
+ report["peers"]["Caddy"] = gateway_artifact.identity
+ kinds = {native_kind(cases[name][1]) for name in selected}
+ if ech and any(cases[name][1].startswith("outer-") for name in selected):
+ kinds.add("XR")
+ if (
+ encryption
+ or jobs is not None
+ or any(
+ native_kind(cases[name][1]) != "M"
+ and (udp or owned or public or "_mux" in cases[name][0])
+ for name in selected
+ )
+ ):
+ kinds.add("M")
+ for kind in sorted(kinds):
+ if supplied is not None:
+ binary, identity = supplied[kind]
+ elif kind == "M":
+ identity = {}
+ binary = download_mihomo(
+ "linux-arm64", directory=output / "binary", identity=identity
+ )
+ else:
+ artifact = download_native(
+ kind, output / kind, "linux-arm64", defer_version=True
+ )
+ binary, identity = artifact.binary, artifact.identity
+ artifacts[kind] = binary
+ report["peers"][kind] = identity
+ lab = ContainerLab(report["isolation"], mtu=1500)
+ build = run_command(
+ [
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ "xhttp_native",
+ *(["--test", "vless_public"] if public or jobs is not None else []),
+ "--no-run",
+ ],
+ timeout=180,
+ )
+ (output / "build.log").write_text(redact(build.stdout.decode(errors="replace")))
+ if build.returncode or not build.cleanup:
+ raise RuntimeError("XHTTP field test build failed")
+ for name in selected:
+ print(name, flush=True)
+ fields, version = cases[name]
+ kind = native_kind(version)
+ entries = jobs[name] if jobs is not None else None
+ needs_public = bool(public) or bool(
+ entries and any(e["test"] in PUBLIC_TESTS for e in entries)
+ )
+ hop_tests = {
+ "runtime::public_graph",
+ "runtime::grpc_pool_keeps_physical_selection_until_new_transport",
+ }
+ needs_hop = public in hop_tests or bool(
+ entries and any(e["test"] in hop_tests for e in entries)
+ )
+ needs_decoder = (
+ bool(encryption)
+ or udp
+ or owned
+ or needs_public
+ or bool(
+ entries
+ and any(
+ e["test"] == "native_xhttp_udp_encodings"
+ or e["test"].startswith("lifecycle::")
+ for e in entries
+ )
+ )
+ )
+ needs_close = bool(
+ entries and any(e["test"].startswith("close::") for e in entries)
+ )
+ outer_mode = (
+ version.removeprefix("outer-") if version.startswith("outer-") else None
+ )
+ identity = report["peers"][kind]
+ with (
+ tempfile.TemporaryDirectory(prefix="private-", dir=output) as temporary,
+ contextlib.ExitStack() as stack,
+ ):
+ root = Path(temporary)
+ server_dir, origin_dir = root / "server", root / "origin"
+ server_dir.mkdir()
+ origin_dir.mkdir()
+ shutil.copy2(artifacts[kind], server_dir / "peer")
+ shutil.copyfile(
+ Path(__file__).with_name("container_udp_origin.py"),
+ origin_dir / "origin.py",
+ )
+ if needs_close:
+ shutil.copyfile(
+ Path(__file__).with_name("container_close_client.py"),
+ origin_dir / "close.py",
+ )
+ origin_security = []
+ if version.endswith(("r", "-reality")) or jls:
+ origin_cert, origin_key, _ = certificates(origin_dir)
+ origin_security = [
+ f"VCORE_ORIGIN_CERT=/data/fixture/{origin_cert.name}",
+ f"VCORE_ORIGIN_KEY=/data/fixture/{origin_key.name}",
+ ]
+ origin = lab.start(
+ stack,
+ origin_dir,
+ name + "-origin",
+ [
+ "env",
+ "VCORE_ISOLATED_ORIGIN=1",
+ *origin_security,
+ "python",
+ "-B",
+ "/data/fixture/origin.py",
+ ],
+ )
+ server = lab.start(
+ stack,
+ server_dir,
+ name + "-server",
+ [
+ "/data/fixture/peer",
+ "-d",
+ "/data",
+ "-f",
+ "/data/fixture/config.json",
+ ]
+ if kind == "M"
+ else [
+ "/data/fixture/peer",
+ "run",
+ "-c",
+ "/data/fixture/config.json",
+ ],
+ )
+ version_text = command(
+ "exec",
+ server.name,
+ "/data/fixture/peer",
+ "-v" if kind == "M" else "version",
+ ).strip()
+ digest = command(
+ "exec", server.name, "sha256sum", "/data/fixture/peer"
+ ).split()[0]
+ if not version_text or digest != identity["binary_sha256"]:
+ raise RuntimeError("XHTTP peer identity mismatch")
+ identity["version"] = version_text
+ cert, key, pin = certificate_chain(server_dir)
+ # Xray always normalizes its handler path with a trailing slash,
+ # unlike Mihomo when both metadata fields are outside the path.
+ # Configure an explicit compatible path, without changing VCore.
+ options = dict(fields, path="/xhttp/" if kind == "XR" else "/xhttp")
+ plain = (
+ not outer_mode.endswith(("-tls", "-reality"))
+ if outer_mode
+ else version.endswith("c")
+ )
+ reality = version.endswith(("r", "-reality"))
+ tiny = options.pop("_tiny", False)
+ keepalive = options.pop("_keepalive", False)
+ reject = options.pop("_reject", False)
+ peer_overrides = options.pop("_server", {})
+ main_alpn = options.pop("_main_alpn", None)
+ mux = options.pop("_mux", None)
+ require_padding = options.pop("_require-padding", False)
+ ech_action = options.pop("_ech_action", None)
+ decoder = None
+ encryption_node = {}
+ if kind != "M" and (needs_decoder or mux is not None):
+ decoder_dir = root / "decoder"
+ decoder_dir.mkdir()
+ shutil.copy2(artifacts["M"], decoder_dir / "peer")
+ listener = dict(
+ name="decoder",
+ type="vless",
+ listen="::",
+ port=23001,
+ users=[dict(uuid=CLIENT_ID)],
+ **{"allow-insecure": True},
+ )
+ if mux is not None:
+ listener["mux-option"] = {
+ "padding": require_padding or mux["padding"]
+ }
+ if encryption:
+ from .protocol_encryption_public import (
+ configuration as encryption_config,
+ )
+
+ encryption_config(
+ encryption, encryption_node, {"listeners": [listener]}
+ )
+ (decoder_dir / "config.json").write_text(
+ json.dumps(
+ dict(
+ ipv6=True,
+ hosts={
+ "vcore-fixture.test": origin.ipv4,
+ "peer.fixture.test": server.ipv4,
+ },
+ listeners=[listener],
+ rules=["MATCH,DIRECT"],
+ **{"log-level": "warning"},
+ )
+ )
+ )
+ decoder = lab.start(
+ stack,
+ decoder_dir,
+ name + "-decoder",
+ [
+ "/data/fixture/peer",
+ "-d",
+ "/data",
+ "-f",
+ "/data/fixture/config.json",
+ ],
+ )
+ decoded_version = command(
+ "exec", decoder.name, "/data/fixture/peer", "-v"
+ ).strip()
+ decoded_digest = command(
+ "exec", decoder.name, "sha256sum", "/data/fixture/peer"
+ ).split()[0]
+ if (
+ not decoded_version
+ or decoded_digest != report["peers"]["M"]["binary_sha256"]
+ ):
+ raise RuntimeError("layered decoder identity mismatch")
+ report["peers"]["M"]["version"] = decoded_version
+ decoder.release()
+ decoder.wait_tcp(23001)
+ node = dict(
+ name="peer",
+ type="vless",
+ server=server.ipv4,
+ port=23000,
+ uuid=CLIENT_ID,
+ tls=not plain,
+ alpn=[
+ "http/1.1"
+ if version.startswith("h1")
+ else "h3"
+ if version == "h3"
+ else "h2"
+ ],
+ **{"xhttp-opts": options},
+ network="xhttp",
+ udp=True,
+ )
+ if mux is not None:
+ node["smux"] = mux
+ if not plain:
+ node.update(servername="localhost", fingerprint=pin)
+ if client_fingerprint:
+ node["client-fingerprint"] = client_fingerprint
+ if main_alpn:
+ node["alpn"] = [main_alpn]
+ config = peer_config(
+ kind,
+ f"/data/fixture/{cert.name}",
+ f"/data/fixture/{key.name}",
+ plain=plain,
+ decoder=decoder.ipv4 if decoder else None,
+ )
+ gateway = None
+ edge = server
+ if main_alpn:
+ # Xray's native listener is either TCP or QUIC, not both.
+ # The approved gateway terminates both TLS legs and feeds
+ # ONE unmodified Xray h2c handler/session table.
+ stream = config["inbounds"][0]["streamSettings"]
+ stream["security"] = "none"
+ del stream["tlsSettings"]
+ gateway_dir = root / "gateway"
+ gateway_dir.mkdir()
+ shutil.copy2(artifacts["Caddy"], gateway_dir / "peer")
+ for filename in ("cert.pem", "key.pem", "root.pem", "root-key.pem"):
+ shutil.copyfile(server_dir / filename, gateway_dir / filename)
+ node.update(client_identities(gateway_dir)["valid"])
+ options["host"] = "localhost"
+ (gateway_dir / "config.json").write_text(
+ json.dumps(selected_gateway_config(server.ipv4))
+ )
+ gateway = lab.start(
+ stack,
+ gateway_dir,
+ name + "-gateway",
+ [
+ "env",
+ "XDG_CONFIG_HOME=/data/config",
+ "XDG_DATA_HOME=/data/share",
+ "/data/fixture/peer",
+ "run",
+ "--config",
+ "/data/fixture/config.json",
+ ],
+ )
+ gateway_version = command(
+ "exec", gateway.name, "/data/fixture/peer", "version"
+ ).strip()
+ gateway_digest = command(
+ "exec", gateway.name, "sha256sum", "/data/fixture/peer"
+ ).split()[0]
+ if (
+ not gateway_version
+ or gateway_digest != report["peers"]["Caddy"]["binary_sha256"]
+ ):
+ raise RuntimeError("selected gateway identity mismatch")
+ report["peers"]["Caddy"]["version"] = gateway_version
+
+ def preserve_gateway(peer=gateway, variant=name):
+ (output / f"{variant}-gateway.log").write_text(
+ sanitized_gateway_log(command("logs", peer.name)[-65536:])
+ )
+
+ stack.callback(preserve_gateway)
+ edge = gateway
+ node["server"] = edge.ipv4
+ if outer_mode:
+ node, config = vless_configuration(
+ outer_mode,
+ server.ipv4,
+ origin.ipv4,
+ Path("/data/fixture") / cert.name,
+ Path("/data/fixture") / key.name,
+ )
+ node["name"] = "peer"
+ if mux is not None:
+ node["smux"] = mux
+ if not plain and not reality:
+ node["fingerprint"] = pin
+ if decoder:
+ config["inbounds"][0].update(
+ protocol="dokodemo-door",
+ settings=dict(
+ address=decoder.ipv4, port=23001, network="tcp"
+ ),
+ )
+ if kind == "M":
+ config["hosts"] = {
+ "vcore-fixture.test": origin.ipv4,
+ "peer.fixture.test": server.ipv4,
+ }
+ if mux is not None:
+ config["listeners"][0]["mux-option"] = {
+ "padding": require_padding or mux["padding"]
+ }
+ if reality:
+ from .mihomo_extended import PRIVATE_KEY, PUBLIC_KEY, SHORT_ID
+
+ listener = config["listeners"][0]
+ listener.pop("certificate", None)
+ listener.pop("private-key", None)
+ listener["reality-config"] = {
+ "dest": f"{origin.ipv4}:24001",
+ "private-key": PRIVATE_KEY,
+ "short-id": [SHORT_ID, ""],
+ "server-names": ["localhost"],
+ }
+ node.pop("fingerprint", None)
+ node["reality-opts"] = {
+ "public-key": PUBLIC_KEY,
+ "short-id": SHORT_ID,
+ }
+ else:
+ config["dns"] = {"hosts": {"vcore-fixture.test": origin.ipv4}}
+ config["outbounds"][0]["settings"] = {"domainStrategy": "UseIP"}
+ if encryption:
+ if decoder:
+ node.update(encryption_node)
+ else:
+ from .protocol_encryption_public import (
+ configuration as encryption_config,
+ )
+
+ encryption_config(encryption, node, config)
+ if jls:
+ from .protocol_jls import configuration as jls_config
+
+ jls_config(node, config, origin.ipv4, name)
+ if ech:
+ from .protocol_ech import configuration as ech_config
+ from .protocol_ech import (
+ legacy_gateway_command,
+ legacy_gateway_config,
+ wrong_key,
+ )
+
+ ech_peer, ech_dir, ech_kind = config, server_dir, kind
+ if outer_mode:
+ # ECH is terminated by official Xray, not a custom TLS
+ # server. V2Ray remains the native legacy transport;
+ # the existing Mihomo decoder owns VLESS/Encryption.
+ stream = config["inbounds"][0]["streamSettings"]
+ tls_options = stream.pop("tlsSettings")
+ stream["security"] = "none"
+ gateway_dir = root / "gateway"
+ gateway_dir.mkdir()
+ shutil.copy2(artifacts["XR"], gateway_dir / "peer")
+ for filename in (cert.name, key.name):
+ shutil.copyfile(
+ server_dir / filename, gateway_dir / filename
+ )
+ ech_peer = legacy_gateway_config(server.ipv4, tls_options)
+ ech_dir, ech_kind = gateway_dir, "XR"
+ ech_material = ech_config(
+ node, ech_peer, ech_dir, name, kind=ech_kind
+ )
+ if outer_mode:
+ (gateway_dir / "config.json").write_text(json.dumps(ech_peer))
+ gateway = lab.start(
+ stack,
+ gateway_dir,
+ name + "-ech-gateway",
+ legacy_gateway_command(),
+ )
+ version_text = command(
+ "exec", gateway.name, "/data/fixture/peer", "version"
+ ).strip()
+ digest = command(
+ "exec", gateway.name, "sha256sum", "/data/fixture/peer"
+ ).split()[0]
+ if (
+ not version_text
+ or digest != report["peers"]["XR"]["binary_sha256"]
+ ):
+ raise RuntimeError("ECH gateway identity mismatch")
+ report["peers"]["XR"]["version"] = version_text
+ edge = gateway
+ node["server"] = edge.ipv4
+
+ def preserve_ech_gateway(peer=gateway, variant=name):
+ (output / f"{variant}-gateway.log").write_text(
+ redact(command("logs", peer.name)[-65536:])
+ )
+
+ stack.callback(preserve_ech_gateway)
+ if ech_action in {"replace", "clear", "reject-download"}:
+ replacement = (
+ {}
+ if ech_action == "clear"
+ else dict(
+ enable=True,
+ config=ech_material["ech_download_config"],
+ )
+ )
+ if ech_action == "reject-download":
+ replacement = wrong_key(replacement)
+ options["download-settings"]["ech-opts"] = replacement
+ elif ech_action == "reject-main":
+ node["ech-opts"] = wrong_key(node["ech-opts"])
+ # Client-only session generator and pacing have no server counterpart.
+ peer_options = {
+ k: v
+ for k, v in options.items()
+ if k
+ not in {
+ "session-table",
+ "session-length",
+ "sc-min-posts-interval-ms",
+ "headers",
+ "reuse-settings",
+ "download-settings",
+ }
+ }
+ peer_options.update(peer_overrides)
+ if outer_mode:
+ pass # Native outer transport options were supplied above.
+ elif kind == "M":
+ config["listeners"][0]["xhttp-config"].update(
+ server_fields(peer_options, kind)
+ )
+ else:
+ config["inbounds"][0]["streamSettings"]["xhttpSettings"].update(
+ server_fields(peer_options, kind)
+ )
+ (server_dir / "config.json").write_text(json.dumps(config))
+ hop = None
+ if needs_hop:
+ # An upstream must not dial a VLESS listener in its own
+ # Mihomo process: that correctly triggers loopback protection.
+ upstream_dir = root / "upstream"
+ upstream_dir.mkdir()
+ shutil.copy2(artifacts["M"], upstream_dir / "peer")
+ (upstream_dir / "config.json").write_text(
+ json.dumps(
+ dict(
+ ipv6=True,
+ hosts={
+ "peer.fixture.test": server.ipv4,
+ "vcore-fixture.test": origin.ipv4,
+ },
+ listeners=[
+ dict(
+ name="hop",
+ type="socks",
+ listen="::",
+ port=23004,
+ udp=True,
+ )
+ ],
+ rules=["MATCH,DIRECT"],
+ **{"log-level": "warning"},
+ )
+ )
+ )
+ upstream = lab.start(
+ stack,
+ upstream_dir,
+ name + "-upstream",
+ [
+ "/data/fixture/peer",
+ "-d",
+ "/data",
+ "-f",
+ "/data/fixture/config.json",
+ ],
+ )
+ upstream.release()
+ upstream.wait_tcp(23004)
+ hop = dict(
+ name="hop",
+ type="socks5",
+ server=upstream.ipv4,
+ port=23004,
+ udp=True,
+ )
+ fixture = root / "input.json"
+ fixture.write_text(
+ json.dumps(
+ dict(
+ isolation="containers",
+ node=node,
+ tiny=tiny,
+ reject=reject,
+ peer_kind=f"{kind}-to-M"
+ if encryption and decoder
+ else kind,
+ data_dir=str(root / "data"),
+ server_ipv4=edge.ipv4,
+ server_ipv6=edge.ipv6,
+ hop=hop,
+ origin_control=f"{origin.ipv4}:24000",
+ origin_ipv4=origin.ipv4,
+ origin_ipv6=origin.ipv6,
+ root_der=list(
+ ssl.PEM_cert_to_DER_cert(
+ (server_dir / "root.pem").read_text()
+ )
+ ),
+ )
+ )
+ )
+ origin.release()
+ server.release()
+ if gateway:
+ gateway.release()
+ origin.wait_tcp(24000)
+ if kind == "M" or gateway:
+ server.wait_tcp(23000)
+ if gateway:
+ gateway.wait_tcp(23000)
+ default_assertion = (
+ public
+ or (
+ "keepalive::native_h3_keepalive_observes_each_leg_and_stop"
+ if keepalive
+ else None
+ )
+ or ("security::native_xhttp_security" if reject else None)
+ or (
+ "lifecycle::native_xhttp_owned_resources"
+ if owned
+ else "native_xhttp_udp_encodings"
+ if udp
+ else "native_xhttp_request_fields"
+ )
+ )
+ if needs_close:
+ try:
+ reference = close_reference(
+ lab, stack, root, name, node, origin, artifacts["M"], output
+ )
+ finally:
+ # A failed reference setup precedes the VCore cases;
+ # preserve its peer evidence before ExitStack cleanup.
+ for role, peer in (("server", server), ("origin", origin)):
+ (output / f"{name}-{role}.log").write_text(
+ redact(command("logs", peer.name)[-65536:])
+ )
+ data = json.loads(fixture.read_text())
+ data["close_reference"] = reference
+ fixture.write_text(json.dumps(data))
+ for entry in entries or [dict(case_id=name, test=default_assertion)]:
+ case_id, assertion = entry["case_id"], entry["test"]
+ events = output / f"{case_id}-events.jsonl"
+ command_line = [
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ "vless_public" if assertion in PUBLIC_TESTS else "xhttp_native",
+ assertion,
+ "--",
+ "--exact",
+ "--ignored",
+ "--nocapture",
+ ]
+ result = run_command(
+ command_line,
+ timeout=240
+ if assertion.startswith("lifecycle::")
+ or assertion in PUBLIC_TESTS
+ else 150,
+ env=dict(
+ os.environ,
+ VCORE_XHTTP_INPUT=str(fixture),
+ VCORE_VLESS_INPUT=str(fixture),
+ VCORE_PROTOCOL_STAGE="XHTTP",
+ VCORE_CASE_EVENTS=str(events),
+ ),
+ )
+ (output / f"{case_id}.log").write_text(
+ redact(result.stdout.decode(errors="replace"))
+ )
+ observed = read_events(events) if events.exists() else []
+ passed = (
+ result.returncode == 0
+ and result.cleanup
+ and (
+ public_events_pass(observed, assertion)
+ if assertion in PUBLIC_TESTS
+ else events_pass(
+ observed,
+ assertion,
+ owned=assertion.startswith("lifecycle::"),
+ )
+ )
+ )
+ report["cases"].append(
+ dict(
+ case_id=case_id,
+ variant=name,
+ assertion=assertion,
+ status="PASS" if passed else "FAIL",
+ command=command_line,
+ exit_code=result.returncode,
+ seconds=result.seconds,
+ command_cleanup=result.cleanup,
+ decoder_path=(
+ (
+ "Xray ECH -> "
+ if ech and outer_mode
+ else "Caddy H2/H3 -> "
+ if gateway
+ else ""
+ )
+ + f"{kind} {outer_mode or 'XHTTP'} -> Mihomo VLESS"
+ )
+ if decoder
+ else kind,
+ )
+ )
+ print(f"{case_id}: {'PASS' if passed else 'FAIL'}", flush=True)
+ if not passed:
+ break
+ for role, peer in (("server", server), ("origin", origin)):
+ peer.ensure_alive()
+ (output / f"{name}-{role}.log").write_text(
+ redact(command("logs", peer.name)[-65536:])
+ )
+ if decoder:
+ decoder.ensure_alive()
+ if gateway:
+ gateway.ensure_alive()
+ if needs_hop:
+ upstream.ensure_alive()
+ (output / f"{name}-upstream.log").write_text(
+ redact(command("logs", upstream.name)[-65536:])
+ )
+ if not passed:
+ break
+ report["status"] = (
+ "PASS"
+ if len(report["cases"])
+ == (sum(map(len, jobs.values())) if jobs is not None else len(selected))
+ and all(c["status"] == "PASS" for c in report["cases"])
+ else "FAIL"
+ )
+ except (OSError, ValueError, RuntimeError) as error:
+ report.update(
+ status="FAIL",
+ reason=str(error)
+ if isinstance(error, RuntimeError)
+ else type(error).__name__,
+ )
+ except KeyboardInterrupt:
+ report.update(status="INTERRUPTED")
+ finally:
+ report["cleanup"] = all(
+ p["joined"] for p in report["isolation"].get("peers", [])
+ )
+ report["source_unchanged"] = (
+ source_identity()["source_tree_sha256"]
+ == report["source"]["source_tree_sha256"]
+ )
+ if not report["cleanup"] or not report["source_unchanged"]:
+ report["status"] = "FAIL"
+ (output / "xhttp-fields-results.json").write_text(
+ json.dumps(report, indent=2) + "\n"
+ )
+ return 0 if report["status"] == "PASS" else 1
+
+
+if __name__ == "__main__":
+ import argparse
+ import sys
+
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("output", type=Path)
+ parser.add_argument("cases", nargs="*")
+ parser.add_argument("--udp", action="store_true")
+ parser.add_argument("--owned", action="store_true")
+ parser.add_argument("--public", choices=PUBLIC_TESTS)
+ parser.add_argument("--encryption")
+ parser.add_argument("--ech", action="store_true")
+ args = parser.parse_args()
+ if sum((args.udp, args.owned, args.public is not None)) > 1:
+ parser.error("select UDP or owned-resource checks")
+ with exclusive_run():
+ sys.exit(
+ run(
+ args.output.resolve(),
+ args.cases,
+ udp=args.udp,
+ owned=args.owned,
+ public=args.public,
+ encryption=args.encryption,
+ ech=args.ech,
+ )
+ )
diff --git a/scripts/src/vcore_scripts/protocol_xhttp_gateway.py b/scripts/src/vcore_scripts/protocol_xhttp_gateway.py
new file mode 100644
index 0000000..4068eaf
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_xhttp_gateway.py
@@ -0,0 +1,564 @@
+"""Isolated xcaddy H3/mTLS -> one native Xray XHTTP handler probe.
+
+Native comparator evidence only: this never claims VCore XHTTP acceptance.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import ipaddress
+import json
+import select
+import shutil
+import socket
+import struct
+import tempfile
+import time
+from pathlib import Path
+
+from .builds import CORE_DIR
+from .caddy_build import build_caddy
+from .container_close_client import exact
+from .mihomo_isolation import exclusive_run
+from .mihomo_release import download_mihomo
+from .native_release import PeerArtifact, download_native
+from .protocol_containers import ContainerLab, command, listing
+from .protocol_fixtures import certificate_chain
+from .protocol_inputs import redact, source_identity
+from .protocol_peers import run_command
+from .protocol_vless_security import client_identities
+from .protocol_xhttp_peers import client_config, exercise, peer_config, socks
+
+
+def sanitized_gateway_log(text):
+ """Keep native protocol evidence, not HTTP headers, identities or destinations."""
+ entries = []
+ events = {
+ "aborting with incomplete response": "response_canceled",
+ "strict SNI-Host enforcement": "strict_sni_host",
+ "admin endpoint disabled": "admin_disabled",
+ "unable to create folder for config autosave": "autosave_failed",
+ "unable to get instance ID": "storage_id_failed",
+ }
+ for line in text.splitlines():
+ try:
+ row = json.loads(line)
+ except ValueError:
+ entries.append({"event": "non_json_log", "omitted": True})
+ continue
+ message = row.get("msg", "")
+ entry = {
+ "level": row.get("level"),
+ "event": next(
+ (name for pattern, name in events.items() if pattern in message),
+ "other_native_event",
+ ),
+ }
+ request = row.get("request", {})
+ if request:
+ entry.update(
+ http_version=request.get("proto"),
+ alpn=request.get("tls", {}).get("proto"),
+ client_certificate_present=bool(
+ request.get("tls", {}).get("client_common_name")
+ ),
+ )
+ entries.append(entry)
+ return "".join(json.dumps(entry) + "\n" for entry in entries)
+
+
+def gateway_config(upstream):
+ address = ipaddress.ip_address(upstream)
+ authority = f"[{address}]" if address.version == 6 else str(address)
+ return {
+ "admin": {"disabled": True},
+ "storage": {"module": "file_system", "root": "/data/caddy"},
+ "logging": {"logs": {"default": {"level": "WARN"}}},
+ "apps": {
+ "tls": {
+ "certificates": {
+ "load_files": [
+ {
+ "certificate": "/data/fixture/cert.pem",
+ "key": "/data/fixture/key.pem",
+ }
+ ]
+ }
+ },
+ "http": {
+ "servers": {
+ "fixture": {
+ "listen": [":23000"],
+ "protocols": ["h3"],
+ "automatic_https": {"disable": True},
+ "tls_connection_policies": [
+ {
+ "client_authentication": {
+ "mode": "require_and_verify",
+ "ca": {
+ "provider": "file",
+ "pem_files": ["/data/fixture/root.pem"],
+ },
+ }
+ }
+ ],
+ "routes": [
+ {
+ "handle": [
+ {
+ "handler": "reverse_proxy",
+ "upstreams": [{"dial": f"{authority}:23000"}],
+ "transport": {
+ "protocol": "http",
+ "versions": ["h2c"],
+ "compression": False,
+ },
+ }
+ ]
+ }
+ ],
+ }
+ }
+ },
+ },
+ }
+
+
+def cases(*, identities_only=False):
+ for mode in ("packet-up", "stream-up", "stream-one"):
+ for split in (False, True) if mode != "stream-one" else (False,):
+ prefix = mode + ("-download" if split else "")
+ checks = (
+ ("echo",)
+ if identities_only
+ else ("echo", "bulk-server-first", "close", "udp")
+ )
+ for check in checks:
+ yield dict(id=f"{prefix}-{check}", mode=mode, split=split, check=check)
+ if split or identities_only:
+ for leg in ("upload", "download") if split else ("shared",):
+ for identity in ("absent", "expired", "wrong-ca"):
+ yield dict(
+ id=f"{prefix}-{leg}-{identity}",
+ mode=mode,
+ split=split,
+ check="reject",
+ leg=leg,
+ identity=identity,
+ )
+
+
+def native_config():
+ config = peer_config("XR", "unused", "unused")
+ stream = config["inbounds"][0]["streamSettings"]
+ stream["security"] = "none"
+ del stream["tlsSettings"]
+ # This ONE handler owns the upload and download session table. Caddy does
+ # not decode XHTTP or VLESS; h2c avoids H1 full-duplex/buffering differences.
+ return config
+
+
+def stream_check(proxy, port, origin, *, bulk):
+ with socket.create_connection((origin, 24000), timeout=15) as control:
+ control.sendall(b"\x0a" if bulk else b"\x0b")
+ target = struct.unpack("!H", exact(control, 2))[0]
+ stream, _ = socks(proxy, port, 1, origin, target)
+ with stream:
+ stream.settimeout(15)
+ if exact(stream, 5) != b"hello":
+ raise ValueError("missing native server-first data")
+ size = 10 * 1024 * 1024 if bulk else 4
+ payload = b"\x5a" * size if bulk else b"ping"
+ stream.sendall(payload)
+ observed = hashlib.sha256()
+ remaining = size
+ while remaining:
+ data = exact(stream, min(65536, remaining))
+ observed.update(data)
+ remaining -= len(data)
+ expected = hashlib.sha256(payload).hexdigest()
+ if observed.hexdigest() != expected:
+ raise ValueError("gateway data mismatch")
+ if bulk and exact(stream, 7) != b"trailer":
+ raise ValueError("missing complete native reply")
+ stream.settimeout(5)
+ started = time.monotonic()
+ stream.shutdown(socket.SHUT_WR)
+ tail = bytearray()
+ try:
+ while data := stream.recv(1024):
+ tail.extend(data)
+ if len(tail) > 1024:
+ raise ValueError("gateway close exceeded response bound")
+ except ConnectionResetError:
+ pass
+ control.settimeout(5)
+ if exact(control, 2) != b"AD":
+ raise ValueError("native origin did not finish")
+ return dict(
+ bytes_each_way=size,
+ sha256=expected,
+ server_first=True,
+ closed=True,
+ close_seconds=round(time.monotonic() - started, 3),
+ tail_after_upload_eof=len(tail),
+ origin_finished=True,
+ )
+
+
+def rejected_identity(proxy, port, origin):
+ with socket.create_connection((origin, 24000), timeout=5) as control:
+ control.sendall(b"\x0c")
+ target = struct.unpack("!H", exact(control, 2))[0]
+ connected = False
+ outcome = "closed"
+ try:
+ stream, _ = socks(proxy, port, 1, origin, target)
+ with stream:
+ stream.sendall(b"synthetic-probe")
+ connected = exact(stream, 2) == b"ok"
+ except TimeoutError:
+ outcome = "timeout" # Never infer rejection from a blackhole.
+ except (OSError, ValueError):
+ pass
+ ready, _, _ = select.select([control], [], [], 0.3)
+ return dict(
+ rejected=not connected and not ready and outcome == "closed",
+ data_exchanged=connected,
+ origin_accepted=bool(ready),
+ client_outcome=outcome,
+ quiet_seconds=0.3,
+ )
+
+
+def run(output: Path, *, identities_only=False):
+ output = output.resolve()
+ if output.parent != (CORE_DIR / "target/interop/runs").resolve():
+ raise ValueError("gateway output must be a fresh target/interop/runs child")
+ output.mkdir(parents=True, exist_ok=False)
+ report = dict(
+ stage="XHTTP-PEERS",
+ purpose="XHTTP-xcaddy-H3-mTLS-prerequisite",
+ vcore_acceptance=False,
+ identities_only=identities_only,
+ source=source_identity(),
+ status="NOT RUN",
+ phase="build",
+ cases=[],
+ peers={},
+ isolation={},
+ topology=(
+ "Mihomo-H3-client -> Caddy-H3-mTLS -> one-Xray-h2c-XHTTP-handler -> origin"
+ ),
+ )
+ try:
+ built = build_caddy(output / "binaries/Caddy")
+ report["phase"] = "download"
+ identity = {}
+ mihomo = PeerArtifact(
+ download_mihomo(
+ "linux-arm64",
+ directory=output / "binaries/M",
+ identity=identity,
+ ),
+ identity,
+ )
+ xray = download_native(
+ "XR", output / "binaries/XR", "linux-arm64", defer_version=True
+ )
+ artifacts = {"Caddy": built, "M": mihomo, "XR": xray}
+ report["peers"] = {
+ kind: artifact.identity for kind, artifact in artifacts.items()
+ }
+ lab = ContainerLab(report["isolation"], mtu=1500)
+ report["phase"] = "start"
+ with tempfile.TemporaryDirectory(prefix="private-", dir=output) as temporary:
+ root = Path(temporary)
+ directories = {
+ role: root / role for role in ("origin", "gateway", "server", "client")
+ }
+ for directory in directories.values():
+ directory.mkdir()
+ origin_dir, gateway_dir, server_dir, client_dir = directories.values()
+ shutil.copyfile(
+ Path(__file__).with_name("container_udp_origin.py"),
+ origin_dir / "origin.py",
+ )
+ shutil.copyfile(
+ Path(__file__).with_name("container_quic_observer.py"),
+ gateway_dir / "observe.py",
+ )
+ for role, artifact in (
+ ("gateway", built),
+ ("server", xray),
+ ("client", mihomo),
+ ):
+ shutil.copyfile(artifact.binary, directories[role] / "peer")
+ (directories[role] / "peer").chmod(0o755)
+ _, _, pin = certificate_chain(gateway_dir)
+ identities = client_identities(gateway_dir)
+ identities["absent"] = {"certificate": "", "private-key": ""}
+ second = root / "second-identity"
+ second.mkdir()
+ for name in ("root.pem", "root-key.pem"):
+ shutil.copyfile(gateway_dir / name, second / name)
+ download_identity = client_identities(second)["valid"]
+ (server_dir / "config.json").write_text(json.dumps(native_config()))
+ with contextlib.ExitStack() as stack:
+ origin = lab.start(
+ stack,
+ origin_dir,
+ "xhttp-gateway-origin",
+ [
+ "env",
+ "VCORE_ISOLATED_ORIGIN=1",
+ "python",
+ "-B",
+ "/data/fixture/origin.py",
+ ],
+ )
+ server = lab.start(
+ stack,
+ server_dir,
+ "xhttp-gateway-xray",
+ [
+ "/data/fixture/peer",
+ "run",
+ "-c",
+ "/data/fixture/config.json",
+ ],
+ )
+ (gateway_dir / "config.json").write_text(
+ json.dumps(gateway_config(server.ipv4))
+ )
+ gateway = lab.start(
+ stack,
+ gateway_dir,
+ "xhttp-gateway-caddy",
+ [
+ "env",
+ "XDG_CONFIG_HOME=/data/config",
+ "XDG_DATA_HOME=/data/share",
+ *(["QLOGDIR=/data/qlog"] if identities_only else []),
+ "/data/fixture/peer",
+ "run",
+ "--config",
+ "/data/fixture/config.json",
+ ],
+ )
+ selected = list(cases(identities_only=identities_only))
+ config = dict(
+ ipv6=True,
+ **{"log-level": "warning"},
+ proxies=[],
+ listeners=[],
+ rules=["MATCH,REJECT"],
+ )
+ for index, case in enumerate(selected):
+ candidate = client_config(
+ gateway.ipv4, pin, "h3", case["mode"], download=case["split"]
+ )
+ node, listener = candidate["proxies"][0], candidate["listeners"][0]
+ node.update(identities["valid"])
+ node["xhttp-opts"]["host"] = "localhost"
+ if case["split"]:
+ node["xhttp-opts"]["download-settings"].update(
+ download_identity
+ )
+ if case["check"] == "reject":
+ target = (
+ node
+ if case["leg"] in ("upload", "shared")
+ else node["xhttp-opts"]["download-settings"]
+ )
+ target.update(identities[case["identity"]])
+ node["name"] = listener["name"] = listener["proxy"] = case["id"]
+ listener["port"] = 23100 + index
+ config["proxies"].append(node)
+ config["listeners"].append(listener)
+ (client_dir / "config.json").write_text(json.dumps(config))
+ client = lab.start(
+ stack,
+ client_dir,
+ "xhttp-gateway-mihomo",
+ [
+ "/data/fixture/peer",
+ "-d",
+ "/data",
+ "-f",
+ "/data/fixture/config.json",
+ ],
+ )
+
+ def preserve_logs():
+ # Snapshot before deletion, independent of log-follow buffering.
+ for role, peer in (
+ ("gateway", gateway),
+ ("server", server),
+ ("client", client),
+ ):
+ (output / f"{role}.log").write_text(
+ sanitized_gateway_log(command("logs", peer.name))
+ if role == "gateway"
+ else redact(command("logs", peer.name))
+ )
+
+ stack.callback(preserve_logs)
+ for kind, peer in (("Caddy", gateway), ("XR", server), ("M", client)):
+ version = command(
+ "exec",
+ peer.name,
+ "/data/fixture/peer",
+ "-v" if kind == "M" else "version",
+ ).strip()
+ digest = command(
+ "exec", peer.name, "sha256sum", "/data/fixture/peer"
+ ).split()[0]
+ if not version or digest != report["peers"][kind]["binary_sha256"]:
+ raise RuntimeError("container binary identity mismatch")
+ if kind == "Caddy" and not version.startswith(
+ report["peers"][kind]["release"] + " "
+ ):
+ raise RuntimeError(
+ "container Caddy version differs from latest source build"
+ )
+ report["peers"][kind]["version"] = version
+ validation = run_command(
+ [
+ "container",
+ "exec",
+ gateway.name,
+ "env",
+ "XDG_CONFIG_HOME=/data/config",
+ "XDG_DATA_HOME=/data/share",
+ "/data/fixture/peer",
+ "validate",
+ "--config",
+ "/data/fixture/config.json",
+ ],
+ timeout=30,
+ limit=65536,
+ )
+ (output / "gateway-validation.log").write_text(
+ redact(validation.stdout.decode(errors="replace"))
+ )
+ if validation.returncode or not validation.cleanup:
+ raise RuntimeError("native Caddy configuration validation failed")
+ for peer in (origin, server, gateway, client):
+ peer.release()
+ origin.wait_tcp(24000)
+ server.wait_tcp(23000)
+ client.wait_tcp(23100)
+ report["phase"] = "traffic"
+
+ def trace_snapshot():
+ return json.loads(
+ command(
+ "exec",
+ gateway.name,
+ "python",
+ "-B",
+ "/data/fixture/observe.py",
+ )
+ )
+
+ for index, case in enumerate(selected):
+ result = dict(case, status="FAIL")
+ before = trace_snapshot() if identities_only else {}
+ started = time.monotonic()
+ try:
+ check = case["check"]
+ args = (client.ipv4, 23100 + index, origin.ipv4)
+ observation = (
+ rejected_identity(*args)
+ if check == "reject"
+ else stream_check(*args, bulk=check == "bulk-server-first")
+ if check in ("bulk-server-first", "close")
+ else exercise(*args, udp=check == "udp")
+ )
+ result.update(observation, status="PASS")
+ if check == "reject" and not observation["rejected"]:
+ result.update(
+ status="FAIL",
+ failure_kind=(
+ "TimeoutError"
+ if observation["client_outcome"] == "timeout"
+ else "OriginAccepted"
+ ),
+ )
+ except (OSError, ValueError) as error:
+ result["failure_kind"] = type(error).__name__
+ if identities_only:
+ after = trace_snapshot()
+ result["gateway_trace_files"] = len(after)
+ result["gateway_new_trace_files"] = len(
+ after.keys() - before.keys()
+ )
+ evidence = [
+ event
+ for key, events in after.items()
+ if key not in before
+ for event in events
+ ]
+ result["gateway_certificate_errors"] = evidence
+ if case["check"] == "reject":
+ expected = {
+ "absent": "certificate_required",
+ "expired": "certificate_expired",
+ "wrong-ca": "unknown_ca",
+ }[case["identity"]]
+ result["identity_enforced"] = any(
+ event["category"] == expected for event in evidence
+ ) and (
+ result.get("origin_accepted") is False
+ and result.get("data_exchanged") is False
+ )
+ if not result["identity_enforced"]:
+ result.update(status="FAIL", evidence_missing=True)
+ result["seconds"] = round(time.monotonic() - started, 3)
+ report["cases"].append(result)
+ print(case["id"], result["status"], flush=True)
+ (output / "result.json").write_text(
+ json.dumps(report, indent=2) + "\n"
+ )
+ for peer in (origin, server, gateway, client):
+ peer.ensure_alive()
+ report["status"] = (
+ "PASS"
+ if all(case["status"] == "PASS" for case in report["cases"])
+ else "FAIL"
+ )
+ report["phase"] = "complete"
+ except BaseException as error:
+ report.update(status="FAIL", failure_kind=type(error).__name__)
+ raise
+ finally:
+ report["source_unchanged"] = report["source"] == source_identity()
+ report["cleanup"] = all(
+ peer.get("joined") for peer in report["isolation"].get("peers", [])
+ )
+ run_id = report["isolation"].get("run_id")
+ report["owned_remaining"] = (
+ [
+ item["id"]
+ for item in listing()
+ if item["configuration"].get("labels", {}).get("vcore-run") == run_id
+ ]
+ if run_id
+ else []
+ )
+ (output / "result.json").write_text(json.dumps(report, indent=2) + "\n")
+ return (
+ 0
+ if report["status"] == "PASS"
+ and report["source_unchanged"]
+ and report["cleanup"]
+ and not report["owned_remaining"]
+ else 1
+ )
+
+
+def main(output, *, identities_only=False):
+ with exclusive_run():
+ return run(output, identities_only=identities_only)
diff --git a/scripts/src/vcore_scripts/protocol_xhttp_peers.py b/scripts/src/vcore_scripts/protocol_xhttp_peers.py
new file mode 100644
index 0000000..8a79382
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_xhttp_peers.py
@@ -0,0 +1,524 @@
+"""XHTTP-PEERS native XHTTP/mux capability probes, not VCore XHTTP acceptance.
+
+Official clients, servers and origins run in owned containers. The host only
+drives SOCKS clients and observes the origin. Direct and layered native decoder
+topologies have separate results; a layered pass never overwrites a direct fail.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import shutil
+import socket
+import struct
+import tempfile
+import time
+from pathlib import Path
+
+from .builds import CORE_DIR
+from .container_close_client import exact
+from .mihomo_isolation import exclusive_run
+from .mihomo_release import download_mihomo
+from .native_release import PeerArtifact, download_native
+from .protocol_containers import ContainerLab, command, listing
+from .protocol_fixtures import certificate_chain, certificates
+from .protocol_inputs import redact, source_identity
+from .protocol_vless_security import client_identities
+
+CLIENT_ID = "07070707-0707-0707-0707-070707070707"
+
+
+def peer_config(kind, cert, key, *, decoder=None, plain=False):
+ if kind == "M":
+ listener = dict(
+ name="xhttp",
+ type="vless",
+ listen="::",
+ port=23000,
+ users=[dict(uuid=CLIENT_ID)],
+ **{"xhttp-config": dict(path="/xhttp", mode="auto")},
+ )
+ if plain:
+ listener["allow-insecure"] = True
+ else:
+ listener.update(certificate=cert, **{"private-key": key})
+ return dict(
+ ipv6=True,
+ **{"log-level": "warning"},
+ listeners=[listener],
+ rules=["MATCH,DIRECT"],
+ )
+ inbound = dict(
+ listen="::",
+ port=23000,
+ protocol="vless",
+ settings=dict(clients=[dict(id=CLIENT_ID)], decryption="none"),
+ streamSettings=dict(
+ network="xhttp",
+ security="tls",
+ tlsSettings=dict(
+ alpn=["h3"], certificates=[dict(certificateFile=cert, keyFile=key)]
+ ),
+ xhttpSettings=dict(path="/xhttp", mode="auto"),
+ ),
+ )
+ if decoder:
+ # The same Xray XHTTP handler owns both legs. It forwards the resulting
+ # byte stream to a real Mihomo VLESS decoder, without parsing its bytes.
+ inbound.update(
+ protocol="dokodemo-door",
+ settings=dict(address=decoder, port=23001, network="tcp"),
+ )
+ return dict(
+ log=dict(loglevel="warning"),
+ inbounds=[inbound],
+ outbounds=[dict(protocol="freedom")],
+ )
+
+
+def client_config(
+ server, pin, version, mode, *, download=False, mux=None, codec="xudp", plain=False
+):
+ node = dict(
+ name="probe",
+ type="vless",
+ server=server,
+ port=23000,
+ uuid=CLIENT_ID,
+ tls=not plain,
+ udp=True,
+ network="xhttp",
+ servername="localhost",
+ alpn=["http/1.1" if version == "h1" else version],
+ **{"packet-encoding": codec, "xhttp-opts": dict(path="/xhttp", mode=mode)},
+ )
+ if not plain:
+ node["fingerprint"] = pin
+ if download:
+ node["xhttp-opts"]["download-settings"] = {}
+ if mux:
+ node["smux"] = dict(enabled=True, protocol=mux)
+ return dict(
+ ipv6=True,
+ **{"log-level": "warning"},
+ proxies=[node],
+ listeners=[
+ dict(
+ name="consumer",
+ type="socks",
+ listen="::",
+ port=23002,
+ udp=True,
+ proxy="probe",
+ )
+ ],
+ rules=["MATCH,REJECT"],
+ )
+
+
+def identity_peer_config(kind, cert, key, ca):
+ config = peer_config(kind, cert, key)
+ if kind == "M":
+ config["listeners"][0].update(
+ {"client-auth-type": "require-and-verify", "client-auth-cert": ca}
+ )
+ else:
+ # Xray's published verify usage adds RootCAs; it is NOT client auth.
+ # This probe checks whether a client identity is actually enforced,
+ # without inventing an unsupported client-auth option for that peer.
+ tls = config["inbounds"][0]["streamSettings"]["tlsSettings"]
+ tls["certificates"].append(dict(certificateFile=ca, usage="verify"))
+ return config
+
+
+def variants():
+ for mode in ("packet-up", "stream-up", "stream-one"):
+ yield dict(name=mode, mode=mode)
+ if mode != "stream-one":
+ yield dict(name=mode + "-download", mode=mode, download=True)
+ yield dict(name="packetaddr", mode="packet-up", codec="packetaddr")
+ for mux in ("h2mux", "smux", "yamux"):
+ yield dict(name=mux, mode="packet-up", mux=mux)
+
+
+def socks(proxy, port, command_id, target, target_port):
+ connection = socket.create_connection((proxy, port), timeout=5)
+ try:
+ connection.sendall(b"\x05\x01\x00")
+ if exact(connection, 2) != b"\x05\x00":
+ raise ValueError("SOCKS greeting rejected")
+ connection.sendall(
+ bytes([5, command_id, 0, 1])
+ + socket.inet_aton(target)
+ + struct.pack("!H", target_port)
+ )
+ reply = exact(connection, 4)
+ if reply[:3] != b"\x05\x00\x00" or reply[3] != 1:
+ raise ValueError("SOCKS request rejected")
+ address = socket.inet_ntoa(exact(connection, 4))
+ relay_port = struct.unpack("!H", exact(connection, 2))[0]
+ return connection, (proxy if address == "0.0.0.0" else address, relay_port)
+ except BaseException:
+ connection.close()
+ raise
+
+
+def exercise(proxy, port, origin, *, udp=False):
+ """One small positive data probe; no retry, no full stage coverage claim."""
+ payload = b"xhttp-native-decoder-probe" * 3
+ with socket.create_connection((origin, 24000), timeout=5) as control:
+ control.sendall(b"\x04" if udp else b"\x0d")
+ target_port = struct.unpack("!H", exact(control, 2))[0]
+ connection, relay = socks(
+ proxy,
+ port,
+ 3 if udp else 1,
+ "0.0.0.0" if udp else origin,
+ 0 if udp else target_port,
+ )
+ with connection:
+ if not udp:
+ connection.sendall(payload)
+ if (
+ exact(connection, len(payload)) != payload
+ or exact(control, 1) != b"A"
+ ):
+ raise ValueError("native TCP mismatch")
+ else:
+ with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as datagram:
+ datagram.settimeout(5)
+ datagram.bind(("0.0.0.0", 0))
+ address = (
+ b"\x01"
+ + socket.inet_aton(origin)
+ + struct.pack("!H", target_port)
+ )
+ datagram.sendto(b"\x00\x00\x00" + address + payload, relay)
+ reply, source = datagram.recvfrom(2048)
+ if source != relay or reply != b"\x00\x00\x00" + address + payload:
+ raise ValueError("native UDP mismatch")
+ observed = exact(control, 4)
+ length = struct.unpack("!H", observed[:2])[0]
+ if length != len(payload) or exact(control, length) != payload:
+ raise ValueError("native origin mismatch")
+ return dict(bytes=len(payload), exact_echo=True, origin_observed=True)
+
+
+def run(output: Path, *, identities_only=False):
+ output = output.resolve()
+ if output.parent != (CORE_DIR / "target/interop/runs").resolve():
+ raise ValueError(
+ "native probe output must be a fresh target/interop/runs child"
+ )
+ output.mkdir(parents=True, exist_ok=False)
+ report = dict(
+ stage="XHTTP-PEERS",
+ purpose="XHTTP-H3-client-identity-prerequisite"
+ if identities_only
+ else "XHTTP-native-prerequisites",
+ vcore_acceptance=False,
+ source=source_identity(),
+ status="NOT RUN",
+ cases=[],
+ peers={},
+ isolation={},
+ )
+ try:
+ artifacts = {}
+ for kind in ("M", "XR"):
+ directory = output / "binaries" / kind
+ if kind == "M":
+ identity = {}
+ artifacts[kind] = PeerArtifact(
+ download_mihomo(
+ "linux-arm64", directory=directory, identity=identity
+ ),
+ identity,
+ )
+ else:
+ artifacts[kind] = download_native(
+ kind, directory, "linux-arm64", defer_version=True
+ )
+ report["peers"][kind] = artifacts[kind].identity
+ # Go QUIC peers send 1280-byte Initial UDP payloads. A 1280-byte guest
+ # L3 interface cannot carry those plus IP/UDP headers. This changes only
+ # these disposable guests, never the shared network or host interface.
+ lab = ContainerLab(report["isolation"], mtu=1500)
+ with (
+ tempfile.TemporaryDirectory(prefix="private-", dir=output) as temporary,
+ contextlib.ExitStack() as stack,
+ ):
+ root = Path(temporary)
+ origin_dir = root / "origin"
+ origin_dir.mkdir()
+ shutil.copyfile(
+ Path(__file__).with_name("container_udp_origin.py"),
+ origin_dir / "origin.py",
+ )
+ origin = lab.start(
+ stack,
+ origin_dir,
+ "xhttp-origin",
+ [
+ "env",
+ "VCORE_ISOLATED_ORIGIN=1",
+ "python",
+ "-B",
+ "/data/fixture/origin.py",
+ ],
+ )
+ origin.release()
+ origin.wait_tcp(24000)
+ decoder_dir = root / "decoder"
+ decoder_dir.mkdir()
+ shutil.copy2(artifacts["M"].binary, decoder_dir / "peer")
+ (decoder_dir / "config.json").write_text(
+ json.dumps(
+ dict(
+ ipv6=True,
+ **{"log-level": "warning"},
+ listeners=[
+ dict(
+ name="decoder",
+ type="vless",
+ listen="::",
+ port=23001,
+ users=[dict(uuid=CLIENT_ID)],
+ **{"allow-insecure": True},
+ )
+ ],
+ rules=["MATCH,DIRECT"],
+ )
+ )
+ )
+ decoder = lab.start(
+ stack,
+ decoder_dir,
+ "xhttp-decoder",
+ [
+ "/data/fixture/peer",
+ "-d",
+ "/data",
+ "-f",
+ "/data/fixture/config.json",
+ ],
+ )
+ decoder.release()
+ decoder.wait_tcp(23001)
+ groups = (
+ ("M", "h1", True, False),
+ ("M", "h2", True, False),
+ ("M", "h1", False, False),
+ ("M", "h2", False, False),
+ ("XR", "h3", False, False),
+ ("XR", "h3", False, True),
+ )
+ if identities_only:
+ groups = (("M", "h2", False, False), ("XR", "h3", False, False))
+ for kind, version, plain, layered in groups:
+ security = "plain" if plain else "tls"
+ topology = "layered" if layered else "direct"
+ label = f"{kind}-{version}-{security}-{topology}"
+ with contextlib.ExitStack() as group:
+ server_dir, client_dir = (
+ root / (label + "-server"),
+ root / (label + "-client"),
+ )
+ server_dir.mkdir()
+ client_dir.mkdir()
+
+ def preserve_logs(
+ server_dir=server_dir, client_dir=client_dir, label=label
+ ):
+ for role, directory in (
+ ("server", server_dir),
+ ("client", client_dir),
+ ):
+ log = directory / "peer.log"
+ if log.exists():
+ (output / f"{label}-{role}.log").write_text(
+ redact(log.read_text(errors="replace"))
+ )
+
+ # Runs after peer stop/join, before temporary keys/configs
+ # are removed. No credentials or configs are copied out.
+ group.callback(preserve_logs)
+ shutil.copy2(artifacts[kind].binary, server_dir / "peer")
+ shutil.copy2(artifacts["M"].binary, client_dir / "peer")
+ cert, key, pin = (
+ certificate_chain(server_dir)
+ if identities_only
+ else certificates(server_dir)
+ )
+ config = peer_config(
+ kind,
+ "/data/fixture/" + cert.name,
+ "/data/fixture/" + key.name,
+ decoder=decoder.ipv4 if layered else None,
+ plain=plain,
+ )
+ identities = {}
+ if identities_only:
+ identities = client_identities(server_dir)
+ identities["absent"] = {"certificate": "", "private-key": ""}
+ config = identity_peer_config(
+ kind,
+ "/data/fixture/" + cert.name,
+ "/data/fixture/" + key.name,
+ "/data/fixture/root.pem",
+ )
+ (server_dir / "config.json").write_text(json.dumps(config))
+ argv = (
+ [
+ "/data/fixture/peer",
+ "-d",
+ "/data",
+ "-f",
+ "/data/fixture/config.json",
+ ]
+ if kind == "M"
+ else [
+ "/data/fixture/peer",
+ "run",
+ "-c",
+ "/data/fixture/config.json",
+ ]
+ )
+ server = lab.start(group, server_dir, label + "-server", argv)
+ version_text = command(
+ "exec",
+ server.name,
+ "/data/fixture/peer",
+ "-v" if kind == "M" else "version",
+ ).strip()
+ report["peers"][kind]["version"] = version_text
+ # One immutable client config gives every variant its own
+ # listener, node and pool; no API mutation or NAT-key reuse.
+ clients = dict(
+ ipv6=True,
+ **{"log-level": "warning"},
+ proxies=[],
+ listeners=[],
+ rules=["MATCH,REJECT"],
+ )
+ selected = list(variants())
+ if identities_only:
+ selected = [
+ dict(name=name, mode="packet-up", download=True)
+ for name in ("valid", "absent", "expired", "wrong-ca")
+ ]
+ for index, variant in enumerate(selected):
+ kwargs = {k: v for k, v in variant.items() if k != "name"}
+ client = client_config(
+ server.ipv4, pin, version, plain=plain, **kwargs
+ )
+ node, listener = client["proxies"][0], client["listeners"][0]
+ if identities_only:
+ node.update(identities["valid"])
+ node["xhttp-opts"]["download-settings"].update(
+ identities[variant["name"]]
+ )
+ node["name"] = listener["name"] = listener["proxy"] = variant[
+ "name"
+ ]
+ listener["port"] = 23100 + index
+ clients["proxies"].append(node)
+ clients["listeners"].append(listener)
+ (client_dir / "config.json").write_text(json.dumps(clients))
+ client = lab.start(
+ group,
+ client_dir,
+ label + "-client",
+ [
+ "/data/fixture/peer",
+ "-d",
+ "/data",
+ "-f",
+ "/data/fixture/config.json",
+ ],
+ )
+ server.release()
+ client.release()
+ if kind == "M":
+ server.wait_tcp(23000)
+ client.wait_tcp(23100)
+ for index, variant in enumerate(selected):
+ for udp in (False,) if identities_only else (False, True):
+ business = "udp" if udp else "tcp"
+ case = dict(
+ id=f"{label}-{variant['name']}-{business}",
+ topology="Xray-XHTTP-to-Mihomo-VLESS"
+ if layered
+ else "single-native-handler",
+ status="FAIL",
+ )
+ started = time.monotonic()
+ should_connect = (
+ not identities_only or variant["name"] == "valid"
+ )
+ case["expected_data_connected"] = should_connect
+ try:
+ case.update(
+ exercise(
+ client.ipv4, 23100 + index, origin.ipv4, udp=udp
+ ),
+ data_connected=True,
+ status="PASS" if should_connect else "FAIL",
+ )
+ if not should_connect:
+ case["failure_kind"] = "ClientIdentityNotEnforced"
+ except (OSError, ValueError) as error:
+ case["failure_kind"] = type(error).__name__
+ case["data_connected"] = False
+ # A rejected exchange alone is only a peer
+ # prerequisite observation, not an XHTTP negative
+ # gate proving zero business bytes/resources.
+ if not should_connect:
+ case["status"] = "PASS"
+ case["seconds"] = round(time.monotonic() - started, 3)
+ report["cases"].append(case)
+ print(case["id"], case["status"], flush=True)
+ (output / "result.json").write_text(
+ json.dumps(report, indent=2) + "\n"
+ )
+ server.ensure_alive()
+ client.ensure_alive()
+ report["status"] = (
+ "PASS"
+ if all(case["status"] == "PASS" for case in report["cases"])
+ else "FAIL"
+ )
+ except BaseException as error:
+ report["status"] = "FAIL"
+ report["failure_kind"] = type(error).__name__
+ raise
+ finally:
+ report["source_unchanged"] = report["source"] == source_identity()
+ report["cleanup"] = all(
+ peer.get("joined") for peer in report["isolation"].get("peers", [])
+ )
+ run_id = report["isolation"].get("run_id")
+ report["owned_remaining"] = (
+ [
+ item["id"]
+ for item in listing()
+ if item["configuration"].get("labels", {}).get("vcore-run") == run_id
+ ]
+ if run_id
+ else []
+ )
+ (output / "result.json").write_text(json.dumps(report, indent=2) + "\n")
+ return (
+ 0
+ if report["status"] == "PASS"
+ and report["source_unchanged"]
+ and report["cleanup"]
+ and not report["owned_remaining"]
+ else 1
+ )
+
+
+def main(output, *, identities_only=False):
+ with exclusive_run():
+ return run(output, identities_only=identities_only)
diff --git a/scripts/src/vcore_scripts/protocol_xhttp_security.py b/scripts/src/vcore_scripts/protocol_xhttp_security.py
new file mode 100644
index 0000000..2c201ee
--- /dev/null
+++ b/scripts/src/vcore_scripts/protocol_xhttp_security.py
@@ -0,0 +1,494 @@
+"""XHTTP VCore upload/download security against owned native handlers.
+
+H1/H2 use one Mihomo listener with two ports. H3 uses the approved xcaddy
+gateway (two bindings, one Xray h2c handler). Neither topology invents a decoder.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import copy
+import json
+import os
+import shutil
+import ssl
+import tempfile
+from pathlib import Path
+
+from .builds import CORE_DIR
+from .caddy_build import build_caddy
+from .mihomo_isolation import exclusive_run
+from .mihomo_release import download_mihomo
+from .native_release import download_native
+from .protocol_containers import ContainerLab, command, listing
+from .protocol_evidence import read_events
+from .protocol_fixtures import certificate_chain
+from .protocol_inputs import redact, source_identity
+from .protocol_peers import run_command
+from .protocol_vless_security import client_identities
+from .protocol_xhttp_fields import events_pass
+from .protocol_xhttp_gateway import gateway_config, sanitized_gateway_log
+from .protocol_xhttp_peers import CLIENT_ID, peer_config
+
+
+def security_cases(base, identities, download_identity, server_ipv6):
+ """Frozen cases, selected before observing results. No retry or skip-on-error."""
+ for mode in ("packet-up", "stream-up", "stream-one"):
+ node = copy.deepcopy(base)
+ options = node["xhttp-opts"]
+ options["mode"] = mode
+ if mode == "packet-up":
+ options["sc-min-posts-interval-ms"] = "1"
+ yield f"{mode}-shared", node, False, None
+ for identity in ("absent", "expired", "wrong-ca"):
+ invalid = copy.deepcopy(node)
+ invalid.update(identities[identity])
+ if identity == "absent":
+ del invalid["certificate"], invalid["private-key"]
+ yield f"{mode}-shared-{identity}", invalid, True, identity
+ if mode == "stream-one":
+ continue
+ options["download-settings"] = {}
+ yield f"{mode}-inherit", copy.deepcopy(node), False, None
+ download = options["download-settings"]
+ download.update(download_identity)
+ download.update(
+ server=server_ipv6,
+ port=23002,
+ tls=True,
+ servername="localhost",
+ host="localhost",
+ path="/xhttp/",
+ headers={"X-Download": "fixture"},
+ **{"reuse-settings": {}, "fingerprint": "", "name-cert-verify": ""},
+ )
+ yield f"{mode}-replace-dualstack-port", copy.deepcopy(node), False, None
+ download["server"] = "peer.fixture.test"
+ yield f"{mode}-download-domain", copy.deepcopy(node), False, None
+ node["servername"] = "sni.fixture.test"
+ node["name-cert-verify"] = "localhost"
+ if base["alpn"] != ["h3"]:
+ # One native handler accepts both ALPNs; the download has its own policy.
+ download["alpn"] = ["http/1.1"] if base["alpn"] == ["h2"] else ["h2"]
+ yield f"{mode}-name-clear-alpn", copy.deepcopy(node), False, None
+ node["servername"] = "localhost"
+ del node["name-cert-verify"]
+ for leg in ("upload", "download"):
+ for identity in ("absent", "expired", "wrong-ca"):
+ invalid = copy.deepcopy(node)
+ target = (
+ invalid
+ if leg == "upload"
+ else invalid["xhttp-opts"]["download-settings"]
+ )
+ target.update(identities[identity])
+ if identity == "absent" and leg == "upload":
+ del target["certificate"], target["private-key"]
+ yield f"{mode}-{leg}-{identity}", invalid, True, identity
+ for key, value in (
+ ("fingerprint", "00" * 32),
+ ("name-cert-verify", "wrong.fixture.test"),
+ ):
+ invalid = copy.deepcopy(node)
+ invalid["xhttp-opts"]["download-settings"][key] = value
+ yield f"{mode}-download-wrong-{key}", invalid, True, None
+ invalid = copy.deepcopy(node)
+ invalid["skip-cert-verify"] = True
+ invalid["xhttp-opts"]["download-settings"].update(
+ {"skip-cert-verify": False, "servername": "wrong.fixture.test"}
+ )
+ yield f"{mode}-download-false-restores-verify", invalid, True, None
+
+
+def run(output: Path, versions: list[str], *, supplied: dict | None = None):
+ if (
+ not versions
+ or len(versions) != len(set(versions))
+ or not set(versions) <= {"h1", "h2", "h3"}
+ ):
+ raise ValueError("select unique H1/H2/H3 security versions")
+ if (
+ not output.is_relative_to(CORE_DIR / "target/interop/runs")
+ or output == CORE_DIR / "target/interop/runs"
+ ):
+ raise ValueError("security output must be a fresh target/interop/runs child")
+ output.mkdir(exist_ok=False)
+ report = dict(
+ stage="XHTTP",
+ scope="security-development-only",
+ source=source_identity(),
+ status="NOT RUN",
+ cases=[],
+ peers={},
+ isolation={},
+ )
+ try:
+ artifacts = {}
+ if supplied is not None:
+ for kind in ({"M"} if any(v != "h3" for v in versions) else set()) | (
+ {"XR", "Caddy"} if "h3" in versions else set()
+ ):
+ artifacts[kind], report["peers"][kind] = supplied[kind]
+ elif any(v != "h3" for v in versions):
+ identity = {}
+ artifacts["M"] = download_mihomo(
+ "linux-arm64", directory=output / "binaries/M", identity=identity
+ )
+ report["peers"]["M"] = identity
+ if "h3" in versions and supplied is None:
+ for kind, artifact in (
+ ("Caddy", build_caddy(output / "binaries/Caddy")),
+ (
+ "XR",
+ download_native(
+ "XR", output / "binaries/XR", "linux-arm64", defer_version=True
+ ),
+ ),
+ ):
+ artifacts[kind] = artifact.binary
+ report["peers"][kind] = artifact.identity
+ lab = ContainerLab(report["isolation"], mtu=1500)
+ build = run_command(
+ [
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ "xhttp_native",
+ "--no-run",
+ ],
+ timeout=180,
+ )
+ (output / "build.log").write_text(redact(build.stdout.decode(errors="replace")))
+ if build.returncode or not build.cleanup:
+ raise RuntimeError("native security driver build failed")
+ groups = [
+ (version, negative)
+ for version in versions
+ for negative in ((False, True) if version == "h3" else (None,))
+ ]
+ for version, negative in groups:
+ with (
+ tempfile.TemporaryDirectory(prefix="private-", dir=output) as temporary,
+ contextlib.ExitStack() as stack,
+ ):
+ root = Path(temporary)
+ directories = {
+ role: root / role for role in ("origin", "server", "gateway")
+ }
+ for directory in directories.values():
+ directory.mkdir()
+ origin_dir, server_dir, gateway_dir = directories.values()
+ shutil.copyfile(
+ Path(__file__).with_name("container_udp_origin.py"),
+ origin_dir / "origin.py",
+ )
+ origin = lab.start(
+ stack,
+ origin_dir,
+ version + "-origin",
+ [
+ "env",
+ "VCORE_ISOLATED_ORIGIN=1",
+ "python",
+ "-B",
+ "/data/fixture/origin.py",
+ ],
+ )
+ cert_dir = gateway_dir if version == "h3" else server_dir
+ cert, key, pin = certificate_chain(cert_dir)
+ identities = client_identities(cert_dir)
+ identities["absent"] = {"certificate": "", "private-key": ""}
+ second = root / "second"
+ second.mkdir()
+ for filename in ("root.pem", "root-key.pem"):
+ shutil.copyfile(cert_dir / filename, second / filename)
+ download_identity = client_identities(second)["valid"]
+ kind = "XR" if version == "h3" else "M"
+ shutil.copy2(artifacts[kind], server_dir / "peer")
+ config = peer_config(
+ kind, f"/data/fixture/{cert.name}", f"/data/fixture/{key.name}"
+ )
+ if kind == "M":
+ config["hosts"] = {"vcore-fixture.test": origin.ipv4}
+ config["listeners"][0].update(
+ {
+ "port": "23000,23002",
+ "client-auth-type": "require-and-verify",
+ "client-auth-cert": "/data/fixture/root.pem",
+ }
+ )
+ else:
+ stream = config["inbounds"][0]["streamSettings"]
+ stream["security"] = "none"
+ del stream["tlsSettings"]
+ config["dns"] = {"hosts": {"vcore-fixture.test": origin.ipv4}}
+ (server_dir / "config.json").write_text(json.dumps(config))
+ server = lab.start(
+ stack,
+ server_dir,
+ version + "-server",
+ [
+ "/data/fixture/peer",
+ "-d",
+ "/data",
+ "-f",
+ "/data/fixture/config.json",
+ ]
+ if kind == "M"
+ else [
+ "/data/fixture/peer",
+ "run",
+ "-c",
+ "/data/fixture/config.json",
+ ],
+ )
+ peers = [(kind, server)]
+ gateway = None
+ edge = server
+ if version == "h3":
+ shutil.copy2(artifacts["Caddy"], gateway_dir / "peer")
+ shutil.copyfile(
+ Path(__file__).with_name("container_quic_observer.py"),
+ gateway_dir / "observe.py",
+ )
+ gateway = lab.start(
+ stack,
+ gateway_dir,
+ version + "-gateway",
+ [
+ "env",
+ "XDG_CONFIG_HOME=/data/config",
+ "XDG_DATA_HOME=/data/share",
+ *(["QLOGDIR=/data/qlog"] if negative else []),
+ "/data/fixture/peer",
+ "run",
+ "--config",
+ "/data/fixture/config.json",
+ ],
+ )
+ conf = gateway_config(server.ipv4)
+ conf["apps"]["http"]["servers"]["fixture"]["listen"].append(
+ ":23002"
+ )
+ (gateway_dir / "config.json").write_text(json.dumps(conf))
+ peers.append(("Caddy", gateway))
+ edge = gateway
+ for implementation, peer in peers:
+ identity = report["peers"][implementation]
+ actual = command(
+ "exec",
+ peer.name,
+ "/data/fixture/peer",
+ "-v" if implementation == "M" else "version",
+ ).strip()
+ digest = command(
+ "exec", peer.name, "sha256sum", "/data/fixture/peer"
+ ).split()[0]
+ if not actual or digest != identity["binary_sha256"]:
+ raise RuntimeError("native security binary identity mismatch")
+ identity["version"] = actual
+
+ def preserve_logs(peers=peers, version=version, negative=negative):
+ for implementation, peer in peers:
+ text = command("logs", peer.name)[-65536:]
+ (
+ output / f"{version}-{negative}-{implementation}.log"
+ ).write_text(
+ sanitized_gateway_log(text)
+ if implementation == "Caddy"
+ else redact(text)
+ )
+
+ stack.callback(preserve_logs)
+ origin.release()
+ server.release()
+ if gateway:
+ gateway.release()
+ origin.wait_tcp(24000)
+ server.wait_tcp(23000)
+ base = dict(
+ name="peer",
+ type="vless",
+ server=edge.ipv4,
+ port=23000,
+ uuid=CLIENT_ID,
+ udp=True,
+ tls=True,
+ servername="localhost",
+ fingerprint=pin,
+ alpn=["http/1.1" if version == "h1" else version],
+ network="xhttp",
+ **identities["valid"],
+ **{
+ "xhttp-opts": {
+ "path": "/xhttp",
+ "host": "localhost",
+ "headers": {"X-Upload": "fixture"},
+ }
+ },
+ )
+ selected = [
+ case
+ for case in security_cases(
+ base, identities, download_identity, edge.ipv6
+ )
+ if negative is None or case[2] == negative
+ ]
+
+ def trace_snapshot(gateway=gateway, negative=negative):
+ return (
+ json.loads(
+ command(
+ "exec",
+ gateway.name,
+ "python",
+ "-B",
+ "/data/fixture/observe.py",
+ )
+ )
+ if gateway and negative
+ else {}
+ )
+
+ for name, node, reject, expected_identity in selected:
+ case_id = f"{version}-{name}"
+ print(case_id, flush=True)
+ fixture = root / "input.json"
+ fixture.write_text(
+ json.dumps(
+ dict(
+ isolation="containers",
+ node=node,
+ reject=reject,
+ server_ipv4=edge.ipv4,
+ origin_control=f"{origin.ipv4}:24000",
+ origin_ipv4=origin.ipv4,
+ origin_ipv6=origin.ipv6,
+ root_der=list(
+ ssl.PEM_cert_to_DER_cert(
+ (cert_dir / "root.pem").read_text()
+ )
+ ),
+ )
+ )
+ )
+ events = output / f"{case_id}-events.jsonl"
+ assertion = "security::native_xhttp_security"
+ cmd = [
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ "xhttp_native",
+ assertion,
+ "--",
+ "--exact",
+ "--ignored",
+ "--nocapture",
+ ]
+ before = trace_snapshot()
+ result = run_command(
+ cmd,
+ timeout=140,
+ env=dict(
+ os.environ,
+ VCORE_XHTTP_INPUT=str(fixture),
+ VCORE_CASE_EVENTS=str(events),
+ ),
+ )
+ (output / f"{case_id}.log").write_text(
+ redact(result.stdout.decode(errors="replace"))
+ )
+ observation = read_events(events) if events.exists() else []
+ passed = (
+ result.returncode == 0
+ and result.cleanup
+ and events_pass(observation, assertion)
+ )
+ row = dict(
+ case_id=case_id,
+ status="PASS" if passed else "FAIL",
+ command=cmd,
+ exit_code=result.returncode,
+ seconds=result.seconds,
+ command_cleanup=result.cleanup,
+ topology="Caddy H3 -> one Xray h2c handler"
+ if gateway
+ else "one Mihomo handler, two ports",
+ )
+ if gateway and negative:
+ after = trace_snapshot()
+ # QUIC trace files contain only lifecycle records at this
+ # level; retain categories, never identities or packets.
+ evidence = [
+ event
+ for key, records in after.items()
+ if key not in before
+ for event in records
+ ]
+ row["certificate_errors"] = evidence
+ if expected_identity:
+ expected = {
+ "absent": "certificate_required",
+ "expired": "certificate_expired",
+ "wrong-ca": "unknown_ca",
+ }[expected_identity]
+ row["identity_enforced"] = any(
+ e["category"] == expected for e in evidence
+ )
+ if not row["identity_enforced"]:
+ row["status"] = "FAIL"
+ report["cases"].append(row)
+ print(case_id, row["status"], flush=True)
+ if row["status"] != "PASS":
+ raise RuntimeError("native security case failed")
+ for _, peer in peers:
+ peer.ensure_alive()
+ report["status"] = "PASS"
+ except (OSError, ValueError, RuntimeError) as error:
+ report.update(
+ status="FAIL",
+ reason=str(error)
+ if isinstance(error, RuntimeError)
+ else type(error).__name__,
+ )
+ finally:
+ report["cleanup"] = all(
+ p.get("joined") for p in report["isolation"].get("peers", [])
+ )
+ report["source_unchanged"] = report["source"] == source_identity()
+ run_id = report["isolation"].get("run_id")
+ report["owned_remaining"] = (
+ [
+ p["id"]
+ for p in listing()
+ if p["configuration"].get("labels", {}).get("vcore-run") == run_id
+ ]
+ if run_id
+ else []
+ )
+ if (
+ not report["cleanup"]
+ or not report["source_unchanged"]
+ or report["owned_remaining"]
+ ):
+ report["status"] = "FAIL"
+ (output / "xhttp-security-results.json").write_text(
+ json.dumps(report, indent=2) + "\n"
+ )
+ return 0 if report["status"] == "PASS" else 1
+
+
+if __name__ == "__main__":
+ import argparse
+ import sys
+
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("output", type=Path)
+ parser.add_argument("versions", nargs="+", choices=("h1", "h2", "h3"))
+ args = parser.parse_args()
+ with exclusive_run():
+ sys.exit(run(args.output.resolve(), args.versions))
diff --git a/scripts/src/vcore_scripts/tls_client_hello.py b/scripts/src/vcore_scripts/tls_client_hello.py
new file mode 100644
index 0000000..ae03977
--- /dev/null
+++ b/scripts/src/vcore_scripts/tls_client_hello.py
@@ -0,0 +1,186 @@
+"""Bounded, offline TLS ClientHello inspection, not a TLS implementation."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import io
+
+from .container_tls_observer import capture_client_hello
+
+
+class Cursor:
+ def __init__(self, data: bytes):
+ self.data, self.at = data, 0
+
+ def take(self, size: int) -> bytes:
+ if size < 0 or self.at + size > len(self.data):
+ raise ValueError("truncated ClientHello")
+ result = self.data[self.at : self.at + size]
+ self.at += size
+ return result
+
+ def number(self, size: int) -> int:
+ return int.from_bytes(self.take(size), "big")
+
+ def vector(self, size: int) -> bytes:
+ return self.take(self.number(size))
+
+ def done(self):
+ if self.at != len(self.data):
+ raise ValueError("unparsed ClientHello data")
+
+
+def _codes(data: bytes) -> list[int]:
+ if len(data) % 2:
+ raise ValueError("odd TLS uint16 vector")
+ return [int.from_bytes(data[i : i + 2], "big") for i in range(0, len(data), 2)]
+
+
+def is_grease(value: int) -> bool:
+ return value & 0x0F0F == 0x0A0A and value >> 8 == value & 0xFF
+
+
+def _shape(hello: dict, shuffle_extensions: bool) -> dict:
+ def normalize(value, key=""):
+ if isinstance(value, dict):
+ return {k: normalize(v, k) for k, v in value.items() if k != "raw_sha256"}
+ if isinstance(value, list):
+ return [normalize(v, key) for v in value]
+ if key in {"ciphers", "values", "type", "group"} and isinstance(value, int):
+ return "GREASE" if is_grease(value) else value
+ return value
+
+ result = normalize(hello)
+ groups = next((e["values"] for e in hello["extensions"] if e["type"] == 10), [])
+ shares = next((e["shares"] for e in hello["extensions"] if e["type"] == 51), [])
+ result["grease_share_group_links"] = [
+ [i for i, group in enumerate(groups) if group == share["group"]]
+ for share in shares
+ if is_grease(share["group"])
+ ]
+ if shuffle_extensions:
+ # Preserve GREASE/padding/PSK positions, sort ONLY the shuffled slots.
+ rows = result["extensions"]
+ slots = [
+ i for i, row in enumerate(rows) if row["type"] not in {"GREASE", 21, 41}
+ ]
+ ordered = sorted((rows[i] for i in slots), key=lambda row: row["type"])
+ for index, row in zip(slots, ordered, strict=True):
+ rows[index] = row
+ return result
+
+
+def compare_client_hellos(
+ expected: bytes, observed: bytes, *, shuffle_extensions: bool = False
+) -> list[str]:
+ """Return differing structural fields; no blanket JA3/ECH/PSK exemption.
+
+ Random values are normalized, not their widths or positions. A caller may
+ separately classify an observed ECH/padding length variant using its pinned
+ template; it is intentionally still reported here.
+ """
+ left = _shape(parse_client_hello(expected), shuffle_extensions)
+ right = _shape(parse_client_hello(observed), shuffle_extensions)
+ return [
+ key
+ for key in sorted(left.keys() | right.keys())
+ if left.get(key) != right.get(key)
+ ]
+
+
+def validate_capture(record: dict) -> dict:
+ """Recompute the retained observation from raw records, not PASS text."""
+ if any(
+ len(record[key]) > 256 * 1024 for key in ("client_hello_b64", "records_b64")
+ ):
+ raise ValueError("capture size limit")
+ wire = base64.b64decode(record["records_b64"], validate=True)
+ raw = base64.b64decode(record["client_hello_b64"], validate=True)
+ records, handshake, layout = capture_client_hello(io.BytesIO(wire).read)
+ parsed = parse_client_hello(raw)
+ if records != wire or handshake != raw or layout != record["records"]:
+ raise ValueError("TLS records differ from retained ClientHello")
+ if parsed != record["parsed"]:
+ raise ValueError("ClientHello evidence differs from raw capture")
+ return parsed
+
+
+def parse_client_hello(data: bytes) -> dict:
+ """Observe an entire handshake message, including its four-byte envelope."""
+ if len(data) > 65536:
+ raise ValueError("ClientHello size limit")
+ cursor = Cursor(data)
+ if cursor.number(1) != 1 or cursor.number(3) != len(data) - 4:
+ raise ValueError("invalid ClientHello envelope")
+ result = {"bytes": len(data), "legacy_version": cursor.number(2)}
+ cursor.take(32)
+ result["session_id_bytes"] = len(cursor.vector(1))
+ result["ciphers"] = _codes(cursor.vector(2))
+ result["compression_methods"] = list(cursor.vector(1))
+ extensions = Cursor(cursor.vector(2))
+ cursor.done()
+ result["extensions"] = []
+ seen = set()
+ while extensions.at < len(extensions.data):
+ kind, payload = extensions.number(2), extensions.vector(2)
+ if kind in seen or len(seen) >= 128:
+ raise ValueError("duplicate or excessive ClientHello extensions")
+ seen.add(kind)
+ row = {"type": kind, "bytes": len(payload)}
+ value = Cursor(payload)
+ if kind in (10, 13, 34, 50):
+ row["values"] = _codes(value.vector(2))
+ elif kind in (27, 43):
+ row["values"] = _codes(value.vector(1))
+ elif kind == 0:
+ names = Cursor(value.vector(2))
+ row["names"] = []
+ while names.at < len(names.data):
+ row["names"].append(
+ {"type": names.number(1), "name": names.vector(2).decode("ascii")}
+ )
+ elif kind in (16, 17513, 17613):
+ protocols = Cursor(value.vector(2))
+ row["protocols"] = []
+ while protocols.at < len(protocols.data):
+ row["protocols"].append(protocols.vector(1).decode("ascii"))
+ elif kind == 51:
+ shares = Cursor(value.vector(2))
+ row["shares"] = []
+ while shares.at < len(shares.data):
+ group, key = shares.number(2), shares.vector(2)
+ share = {"group": group, "bytes": len(key)}
+ if is_grease(group):
+ share["grease_data"] = key.hex()
+ elif group in (23, 24, 25) and key:
+ share["point_format"] = key[0]
+ row["shares"].append(share)
+ elif kind == 65037:
+ row["hello_type"] = value.number(1)
+ if row["hello_type"] != 0:
+ raise ValueError("expected outer ECH structure")
+ row["kdf"], row["aead"] = value.number(2), value.number(2)
+ value.take(1) # Random GREASE config_id remains in the raw evidence.
+ row["enc_bytes"] = len(value.vector(2))
+ row["payload_bytes"] = len(value.vector(2))
+ elif kind == 35:
+ row["ticket_bytes"] = len(value.take(len(payload)))
+ elif kind == 41:
+ identities = Cursor(value.vector(2))
+ row["identities"] = []
+ while identities.at < len(identities.data):
+ row["identities"].append(len(identities.vector(2)))
+ identities.take(4) # Obfuscated age is time-dependent.
+ binders = Cursor(value.vector(2))
+ row["binders"] = []
+ while binders.at < len(binders.data):
+ row["binders"].append(len(binders.vector(1)))
+ if not row["identities"] or len(row["identities"]) != len(row["binders"]):
+ raise ValueError("invalid PSK identity/binder counts")
+ else:
+ row["payload_hex"] = value.take(len(payload)).hex()
+ value.done()
+ result["extensions"].append(row)
+ result["raw_sha256"] = hashlib.sha256(data).hexdigest()
+ return result
diff --git a/scripts/src/vcore_scripts/tun2socks.py b/scripts/src/vcore_scripts/tun2socks.py
index 461820c..6adf350 100644
--- a/scripts/src/vcore_scripts/tun2socks.py
+++ b/scripts/src/vcore_scripts/tun2socks.py
@@ -20,8 +20,6 @@ import time
from pathlib import Path
from urllib.parse import urlparse
-ROOT = Path(__file__).resolve().parents[3]
-XRAY_SOURCE = ROOT / "references" / "Xray-core"
PACKAGE_NAME = "VCore.UwpDemo.Dev"
SOCKS_PORT = 19080
TUN_IPV4 = "192.168.8.1"
@@ -328,11 +326,12 @@ rules:
"""
-def run_demo(source_config: Path | None = None) -> None:
+def run_demo(source_config: Path, *, xray_source: Path) -> None:
if os.name != "nt":
raise RuntimeError("This demo requires Windows")
- source_config = source_config or Path.home() / "lib" / "xray" / "config.json"
- if not source_config.is_file() or not (XRAY_SOURCE / "go.mod").is_file():
+ source_config = source_config.resolve()
+ xray_source = xray_source.resolve()
+ if not source_config.is_file() or not (xray_source / "go.mod").is_file():
raise RuntimeError("Xray source checkout or source config is missing")
package = package_info()
@@ -356,13 +355,13 @@ def run_demo(source_config: Path | None = None) -> None:
str(xray_exe),
"./main",
],
- cwd=XRAY_SOURCE,
+ cwd=xray_source,
env=env,
check=True,
)
revision = subprocess.run(
["git", "rev-parse", "--short", "HEAD"],
- cwd=XRAY_SOURCE,
+ cwd=xray_source,
check=True,
capture_output=True,
text=True,
diff --git a/scripts/tests/test_core_checks.py b/scripts/tests/test_core_checks.py
new file mode 100644
index 0000000..e65b634
--- /dev/null
+++ b/scripts/tests/test_core_checks.py
@@ -0,0 +1,87 @@
+"""Offline checks of the supported validation entrypoint, not milestone counts."""
+
+import contextlib
+import io
+import unittest
+from unittest.mock import patch
+
+from vcore_scripts import cli
+from vcore_scripts.core_checks import commands, validate_execution
+from vcore_scripts.protocol_catalogs import check_protocol_catalogs
+from vcore_scripts.protocol_evidence import check_limit_references, load_manifest
+
+
+class CoreChecksTest(unittest.TestCase):
+ def test_legacy_server_suites_fail_before_acquiring_resources(self):
+ for suite in ("foundations", "trojan"):
+ with (
+ self.subTest(suite=suite),
+ patch("vcore_scripts.protocol_harness.tempfile.mkdtemp") as create_run,
+ patch("subprocess.Popen") as spawn,
+ contextlib.redirect_stderr(io.StringIO()) as error,
+ ):
+ self.assertEqual(
+ cli.main(["check", "protocol-interop", "--suite", suite]), 1
+ )
+ self.assertIn("not fully containerized", error.getvalue())
+ create_run.assert_not_called()
+ spawn.assert_not_called()
+
+ def test_catalog_validity_does_not_claim_executed_behavior(self):
+ with contextlib.redirect_stdout(io.StringIO()) as output:
+ check_protocol_catalogs()
+ self.assertIn('"behavior_status": "NOT RUN"', output.getvalue())
+ check_limit_references(load_manifest())
+
+ def test_profiles_select_tests_without_running_all_target_servers(self):
+ for profile in ("debug", "release", "features"):
+ selected = commands(profile)
+ self.assertTrue(selected)
+ for command in selected:
+ if command[:2] == ["cargo", "test"]:
+ self.assertTrue(
+ "--all-targets" not in command or "--no-run" in command
+ )
+ self.assertNotIn("--ignored", command)
+ if profile != "features":
+ self.assertTrue(
+ all(
+ ("--release" in command) == (profile == "release")
+ for command in selected
+ )
+ )
+ with self.assertRaises(ValueError):
+ commands("missing")
+
+ def test_empty_partial_failed_or_unjoined_execution_fails(self):
+ command = ["cargo", "test", "--test", "one", "--test", "two"]
+ ok = "test result: ok. 2 passed; 0 failed; 0 ignored;"
+ validate_execution(command, ok + "\n" + ok, 0, True)
+ for output, code, cleanup in (
+ ("", 0, True),
+ (ok, 0, True),
+ (ok + "\ntest result: ok. 0 passed; 0 failed; 3 ignored;", 0, True),
+ (ok + "\n" + ok, 1, True),
+ (ok + "\n" + ok, 0, False),
+ ):
+ with (
+ self.subTest(output=output, code=code, cleanup=cleanup),
+ self.assertRaises(RuntimeError),
+ ):
+ validate_execution(command, output, code, cleanup)
+
+ def test_list_mode_is_read_only_and_capability_names_resolve(self):
+ with contextlib.redirect_stdout(io.StringIO()) as output:
+ self.assertEqual(cli.main(["check", "core", "--list"]), 0)
+ self.assertEqual(
+ cli.main(
+ ["check", "protocol-interop", "--suite", "integration", "--list"]
+ ),
+ 0,
+ )
+ self.assertIn("shadowsocks_backpressure", output.getvalue())
+ self.assertIn("INTEGRATION-PAIR-SS-SS", output.getvalue())
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/scripts/tests/test_fingerprint_cli.py b/scripts/tests/test_fingerprint_cli.py
new file mode 100644
index 0000000..5b18af5
--- /dev/null
+++ b/scripts/tests/test_fingerprint_cli.py
@@ -0,0 +1,56 @@
+"""Profile CLI help/listing never acquires a network or starts a test peer."""
+
+import contextlib
+import io
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+from vcore_scripts.mihomo_isolation import exclusive_run
+from vcore_scripts.protocol_fingerprint import main
+
+
+class FingerprintCliTest(unittest.TestCase):
+ def test_help_exposes_explicit_profile_selection_without_running(self):
+ output = io.StringIO()
+ with contextlib.redirect_stdout(output), self.assertRaises(SystemExit) as error:
+ main(["--help"])
+ self.assertEqual(error.exception.code, 0)
+ self.assertIn("--client-fingerprint", output.getvalue())
+ for name in (
+ "none",
+ "chrome",
+ "chrome120",
+ "firefox",
+ "firefox120",
+ "safari",
+ "safari16",
+ ):
+ self.assertIn(name, output.getvalue())
+
+ def test_option_between_output_and_cases_reaches_pre_io_selection_check(self):
+ for name in (
+ "none",
+ "chrome",
+ "chrome120",
+ "firefox",
+ "firefox120",
+ "safari",
+ "safari16",
+ ):
+ # This argument-only test can run inside a locked native suite.
+ # Exercise the real lock on its own temporary filesystem boundary.
+ with (
+ tempfile.TemporaryDirectory() as temporary,
+ patch(
+ "vcore_scripts.protocol_fingerprint.exclusive_run",
+ lambda: exclusive_run(Path(temporary) / "cli.lock"),
+ ),
+ self.assertRaisesRegex(ValueError, "invalid VLESS native selection"),
+ ):
+ main(["unused-output", "--client-fingerprint", name, "missing"])
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/scripts/tests/test_fingerprint_reference.py b/scripts/tests/test_fingerprint_reference.py
new file mode 100644
index 0000000..3e2c6ef
--- /dev/null
+++ b/scripts/tests/test_fingerprint_reference.py
@@ -0,0 +1,82 @@
+"""Offline checks of the selected-profile reference driver interface."""
+
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+from vcore_scripts.builds import CORE_DIR
+from vcore_scripts.protocol_fingerprint_reference import (
+ check_reference_report,
+ reference_cases,
+ run_reference,
+)
+
+
+class FingerprintReferenceTest(unittest.TestCase):
+ def test_partial_or_unclean_reference_is_not_a_completed_baseline(self):
+ for changed in (
+ {"selection": "partial"},
+ {"cleanup": False},
+ {"source_unchanged": False},
+ ):
+ report = dict(
+ scope="selected-v1",
+ status="CAPTURED",
+ selection="full",
+ cleanup=True,
+ source_unchanged=True,
+ cases=[],
+ )
+ report.update(changed)
+ with self.assertRaises(ValueError):
+ check_reference_report(report)
+
+ def test_invalid_selection_has_no_filesystem_or_network_effects(self):
+ with tempfile.TemporaryDirectory() as directory:
+ output = Path(directory) / "not-created"
+ for cases in (
+ [],
+ ["missing"],
+ ["FINGERPRINT-REFERENCE-chrome-tcp-16-0"] * 2,
+ ):
+ with self.assertRaises(ValueError):
+ run_reference(output, cases)
+ self.assertFalse(output.exists())
+
+ def test_catalog_covers_selected_names_contexts_and_successive_connections(self):
+ cases = reference_cases()
+ self.assertEqual(len({case["id"] for case in cases}), len(cases))
+ self.assertEqual(
+ {case["profile"] for case in cases},
+ {
+ "none",
+ "chrome",
+ "chrome120",
+ "firefox",
+ "firefox120",
+ "safari",
+ "safari16",
+ },
+ )
+ for profile in ("chrome", "chrome120", "firefox", "safari"):
+ selected = [c for c in cases if c["profile"] == profile]
+ self.assertEqual(
+ {c["context"] for c in selected},
+ {"tcp", "ws", "grpc", "reality", "tls12", "tls13"},
+ )
+ self.assertEqual({c["attempt"] for c in selected}, {0, 1})
+ self.assertEqual({c["sni_length"] for c in cases}, {16, 80})
+ catalog = {case["id"]: case for case in cases}
+ samples = json.loads(
+ (CORE_DIR / "tests/fingerprints/mihomo-selected-v1.json").read_text()
+ )["samples"]
+ for sample in samples:
+ with self.subTest(sample=sample["case_id"]):
+ case = catalog[sample["case_id"]]
+ for field in ("profile", "context", "template"):
+ self.assertEqual(sample[field], case[field])
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/scripts/tests/test_mihomo_release.py b/scripts/tests/test_mihomo_release.py
new file mode 100644
index 0000000..b16d835
--- /dev/null
+++ b/scripts/tests/test_mihomo_release.py
@@ -0,0 +1,416 @@
+from __future__ import annotations
+
+import gzip
+import hashlib
+import http.client
+import io
+import stat
+import tempfile
+import unittest
+import urllib.error
+import zipfile
+from contextlib import redirect_stdout
+from pathlib import Path
+from unittest.mock import patch
+
+from vcore_scripts import mihomo_release
+
+LATEST_VERSION_URL = (
+ "https://github.com/MetaCubeX/mihomo/releases/latest/download/version.txt"
+)
+RELEASE_BASE = "https://github.com/MetaCubeX/mihomo/releases/download"
+TARGET_ASSET_PREFIXES = {
+ "darwin-arm64": "mihomo-darwin-arm64",
+ "darwin-amd64": "mihomo-darwin-amd64",
+ "linux-arm64": "mihomo-linux-arm64",
+ "linux-amd64": "mihomo-linux-amd64-v1",
+ "windows-arm64": "mihomo-windows-arm64",
+ "windows-amd64": "mihomo-windows-amd64-v1",
+}
+
+
+class Response(io.BytesIO):
+ def __init__(self, contents: bytes, url: str):
+ super().__init__(contents)
+ self.url = url
+
+ def geturl(self):
+ return self.url
+
+ def read(self, size=-1):
+ if size <= 0:
+ raise AssertionError("Network responses must be read in bounded chunks")
+ return super().read(size)
+
+ def read1(self, size=-1):
+ return self.read(size)
+
+
+def zip_contents(entries: list[tuple[str | zipfile.ZipInfo, bytes]]) -> bytes:
+ output = io.BytesIO()
+ with zipfile.ZipFile(output, "w", compression=zipfile.ZIP_DEFLATED) as archive:
+ for name, contents in entries:
+ archive.writestr(name, contents)
+ return output.getvalue()
+
+
+def archive_fixture(target="darwin-arm64", contents=b"fixture executable\n"):
+ if target.startswith("windows-"):
+ return zip_contents([("mihomo.exe", contents)])
+ return gzip.compress(contents, mtime=0)
+
+
+def asset_name(target, tag):
+ suffix = "zip" if target.startswith("windows-") else "gz"
+ return f"{TARGET_ASSET_PREFIXES[target]}-{tag}.{suffix}"
+
+
+class MihomoReleaseTest(unittest.TestCase):
+ def setUp(self):
+ directory = self.enterContext(tempfile.TemporaryDirectory())
+ self.root = Path(directory) / "core"
+ self.enterContext(patch.object(mihomo_release, "CORE_DIR", self.root))
+ self.urlopen = self.enterContext(
+ patch(
+ "urllib.request.urlopen",
+ side_effect=AssertionError("Unexpected network request"),
+ )
+ )
+ self.output = self.enterContext(redirect_stdout(io.StringIO()))
+
+ def binary_path(self, target="darwin-arm64", tag="v1.19.31"):
+ return (
+ self.root
+ / "target"
+ / "interop"
+ / "mihomo"
+ / tag
+ / target
+ / ("mihomo.exe" if target.startswith("windows-") else "mihomo")
+ )
+
+ def archive_url(self, target="darwin-arm64", tag="v1.19.31"):
+ return f"{RELEASE_BASE}/{tag}/{asset_name(target, tag)}"
+
+ def asset_response(self, archive, target="darwin-arm64", tag="v1.19.31"):
+ return Response(archive, self.archive_url(target, tag))
+
+ def version_response(self, tag="v1.19.31"):
+ return Response(f"{tag}\n".encode(), LATEST_VERSION_URL)
+
+ def provide_archive(self, archive, target="darwin-arm64", tag="v1.19.31"):
+ self.urlopen.side_effect = None
+ self.urlopen.return_value = self.asset_response(archive, target, tag)
+
+ def assert_download_rejected(self, archive, target="darwin-arm64"):
+ self.provide_archive(archive, target)
+ with self.assertRaises(RuntimeError):
+ mihomo_release.download_mihomo(target, release="v1.19.31")
+ binary = self.binary_path(target)
+ self.assertFalse(binary.exists())
+ self.assertFalse(any(binary.parent.glob(".download-*")))
+
+ def test_target_mapping_is_pure_and_supports_host_aliases(self):
+ self.assertEqual(
+ set(mihomo_release.SUPPORTED_TARGETS), set(TARGET_ASSET_PREFIXES)
+ )
+ for system in ("Darwin", "Linux", "Windows"):
+ for machine, architecture in (
+ ("arm64", "arm64"),
+ ("aarch64", "arm64"),
+ ("amd64", "amd64"),
+ ("x86_64", "amd64"),
+ ("AMD64", "amd64"),
+ ):
+ with (
+ self.subTest(system=system, machine=machine),
+ patch.object(
+ mihomo_release.platform, "system", return_value=system
+ ),
+ patch.object(
+ mihomo_release.platform, "machine", return_value=machine
+ ),
+ ):
+ self.assertEqual(
+ mihomo_release._target(None), f"{system.lower()}-{architecture}"
+ )
+ for target in TARGET_ASSET_PREFIXES:
+ self.assertEqual(mihomo_release._target(target), target)
+ self.urlopen.assert_not_called()
+ self.assertFalse(self.root.exists())
+
+ def test_unsupported_target_fails_before_network_or_filesystem_changes(self):
+ for target in ("freebsd-amd64", "linux-386", "../../outside"):
+ with self.subTest(target=target), self.assertRaises(RuntimeError):
+ mihomo_release.download_mihomo(target)
+ for system, machine in (("FreeBSD", "amd64"), ("Linux", "riscv64")):
+ with (
+ self.subTest(system=system, machine=machine),
+ patch.object(mihomo_release.platform, "system", return_value=system),
+ patch.object(mihomo_release.platform, "machine", return_value=machine),
+ self.assertRaises(RuntimeError),
+ ):
+ mihomo_release.download_mihomo()
+ self.urlopen.assert_not_called()
+ self.assertFalse(self.root.exists())
+
+ def test_downloads_expected_gzip_and_zip_asset_for_each_target(self):
+ payload = b"offline executable fixture\x00\xff"
+ for target in TARGET_ASSET_PREFIXES:
+ with self.subTest(target=target):
+ archive = archive_fixture(target, payload)
+ self.provide_archive(archive, target)
+ binary = mihomo_release.download_mihomo(target, release="v1.19.31")
+ self.assertEqual(binary, self.binary_path(target))
+ self.assertEqual(binary.read_bytes(), payload)
+ self.assertEqual(list(binary.parent.iterdir()), [binary])
+ request = self.urlopen.call_args.args[0]
+ self.assertEqual(request.full_url, self.archive_url(target))
+ self.assertEqual(request.get_method(), "GET")
+ self.assertEqual(self.urlopen.call_args.kwargs["timeout"], 30)
+ if not target.startswith("windows-"):
+ self.assertTrue(binary.stat().st_mode & stat.S_IXUSR)
+ report = self.output.getvalue()
+ for value in (
+ "v1.19.31",
+ asset_name(target, "v1.19.31"),
+ self.archive_url(target),
+ hashlib.sha256(archive).hexdigest(),
+ hashlib.sha256(payload).hexdigest(),
+ str(binary),
+ ):
+ self.assertIn(value, report)
+
+ def test_latest_release_gets_version_text_on_every_call(self):
+ self.urlopen.side_effect = [
+ Response(b" v1.19.31\r\n", LATEST_VERSION_URL),
+ self.version_response("v1.19.32"),
+ ]
+ self.assertEqual(mihomo_release.latest_release(), "v1.19.31")
+ self.assertEqual(mihomo_release.latest_release(), "v1.19.32")
+ self.assertEqual(self.urlopen.call_count, 2)
+ for call in self.urlopen.call_args_list:
+ self.assertEqual(call.args[0].full_url, LATEST_VERSION_URL)
+ self.assertEqual(call.args[0].get_method(), "GET")
+ self.assertEqual(call.kwargs["timeout"], 30)
+ self.assertFalse(self.root.exists())
+
+ def test_latest_version_change_downloads_into_new_version_directory(self):
+ old_archive = archive_fixture(contents=b"old")
+ new_archive = archive_fixture(contents=b"new")
+ self.urlopen.side_effect = [
+ self.version_response("v1.19.31"),
+ self.asset_response(old_archive, tag="v1.19.31"),
+ self.version_response("v1.19.32"),
+ self.asset_response(new_archive, tag="v1.19.32"),
+ ]
+ old_binary = mihomo_release.download_mihomo("darwin-arm64")
+ new_binary = mihomo_release.download_mihomo("darwin-arm64")
+ self.assertNotEqual(old_binary, new_binary)
+ self.assertEqual(old_binary.read_bytes(), b"old")
+ self.assertEqual(new_binary.read_bytes(), b"new")
+ self.assertEqual(new_binary, self.binary_path(tag="v1.19.32"))
+ self.assertEqual(
+ [call.args[0].full_url for call in self.urlopen.call_args_list],
+ [
+ LATEST_VERSION_URL,
+ self.archive_url(tag="v1.19.31"),
+ LATEST_VERSION_URL,
+ self.archive_url(tag="v1.19.32"),
+ ],
+ )
+
+ def test_same_release_is_downloaded_again_even_when_binary_exists(self):
+ self.urlopen.side_effect = [
+ self.asset_response(archive_fixture(contents=b"first download")),
+ self.asset_response(archive_fixture(contents=b"second download")),
+ ]
+ first = mihomo_release.download_mihomo("darwin-arm64", release="v1.19.31")
+ self.assertEqual(first.read_bytes(), b"first download")
+ second = mihomo_release.download_mihomo("darwin-arm64", release="v1.19.31")
+ self.assertEqual(first, second)
+ self.assertEqual(second.read_bytes(), b"second download")
+ self.assertEqual(self.urlopen.call_count, 2)
+
+ def test_version_lookup_failure_does_not_return_existing_binary(self):
+ binary = self.binary_path()
+ binary.parent.mkdir(parents=True)
+ binary.write_bytes(b"previous valid binary")
+ self.urlopen.side_effect = urllib.error.URLError("offline fixture")
+ with self.assertRaises(RuntimeError):
+ mihomo_release.download_mihomo("darwin-arm64")
+ self.urlopen.assert_called_once()
+ self.assertEqual(self.urlopen.call_args.args[0].full_url, LATEST_VERSION_URL)
+ self.assertEqual(binary.read_bytes(), b"previous valid binary")
+
+ def test_latest_release_rejects_invalid_utf8_unsafe_or_oversized_versions(self):
+ for contents in (
+ b"\xff",
+ b"",
+ b" \n",
+ b"../outside",
+ b"v1/other",
+ b"v1\\other",
+ b".",
+ b"v1\nv2",
+ b'{"tag_name":"v1.19.31"}',
+ b"v" * 129,
+ ):
+ self.urlopen.side_effect = None
+ self.urlopen.return_value = Response(contents, LATEST_VERSION_URL)
+ with self.subTest(contents=contents), self.assertRaises(RuntimeError):
+ mihomo_release.latest_release()
+ self.urlopen.return_value = self.version_response()
+ with (
+ patch.object(mihomo_release, "MAX_VERSION_BYTES", 4),
+ self.assertRaises(RuntimeError),
+ ):
+ mihomo_release.latest_release()
+ self.assertFalse(self.root.exists())
+
+ def test_explicit_unsafe_release_fails_before_network_or_filesystem_changes(self):
+ for tag in ("../outside", "v1/other", "v1\\other", ".", "", "v" * 129):
+ with self.subTest(tag=tag), self.assertRaises(RuntimeError):
+ mihomo_release.download_mihomo("darwin-arm64", release=tag)
+ self.urlopen.assert_not_called()
+ self.assertFalse(self.root.exists())
+
+ def test_network_or_archive_failure_preserves_existing_binary(self):
+ binary = self.binary_path()
+ binary.parent.mkdir(parents=True)
+ binary.write_bytes(b"previous valid binary")
+ for failure in ("network", "archive"):
+ if failure == "network":
+ self.urlopen.side_effect = urllib.error.URLError("offline fixture")
+ else:
+ self.provide_archive(b"invalid gzip")
+ with self.subTest(failure=failure), self.assertRaises(RuntimeError):
+ mihomo_release.download_mihomo("darwin-arm64", release="v1.19.31")
+ self.assertEqual(binary.read_bytes(), b"previous valid binary")
+ self.assertEqual(list(binary.parent.iterdir()), [binary])
+
+ def test_corrupt_gzip_or_zip_never_installs_binary(self):
+ for target in ("darwin-arm64", "windows-amd64"):
+ with self.subTest(target=target):
+ self.assert_download_rejected(b"not an archive", target)
+
+ def test_gzip_crc_failure_after_payload_read_preserves_existing_binary(self):
+ binary = self.binary_path()
+ binary.parent.mkdir(parents=True)
+ binary.write_bytes(b"previous valid binary")
+ archive = bytearray(archive_fixture(contents=b"new binary" * 10000))
+ archive[-8] ^= 0xFF
+ self.provide_archive(bytes(archive))
+ decoded_sizes = []
+ read1 = gzip.GzipFile.read1
+
+ def record_decoded_chunk(source, size=-1):
+ chunk = read1(source, size)
+ decoded_sizes.append(len(chunk))
+ return chunk
+
+ with (
+ patch.object(gzip.GzipFile, "read1", record_decoded_chunk),
+ self.assertRaises(RuntimeError),
+ ):
+ mihomo_release.download_mihomo("darwin-arm64", release="v1.19.31")
+ self.assertGreater(sum(decoded_sizes), 0)
+ self.assertEqual(binary.read_bytes(), b"previous valid binary")
+ self.assertEqual(list(binary.parent.iterdir()), [binary])
+
+ def test_archive_download_is_bounded(self):
+ archive = archive_fixture()
+ with patch.object(mihomo_release, "MAX_ARCHIVE_BYTES", len(archive) - 1):
+ self.assert_download_rejected(archive)
+
+ def test_gzip_and_zip_decompressed_binary_sizes_are_bounded(self):
+ for target in ("darwin-arm64", "windows-amd64"):
+ archive = archive_fixture(target, b"A" * 4096)
+ with (
+ self.subTest(target=target),
+ patch.object(mihomo_release, "MAX_BINARY_BYTES", 128),
+ ):
+ self.assert_download_rejected(archive, target)
+
+ def test_interrupted_http_stream_is_reported_without_installing_binary(self):
+ for version in (True, False):
+ response = (
+ self.version_response()
+ if version
+ else self.asset_response(archive_fixture())
+ )
+ self.urlopen.side_effect = None
+ self.urlopen.return_value = response
+ with (
+ self.subTest(version=version),
+ patch.object(
+ response,
+ "read1",
+ side_effect=http.client.IncompleteRead(b"partial", 100),
+ ),
+ self.assertRaises(RuntimeError),
+ ):
+ if version:
+ mihomo_release.latest_release()
+ else:
+ mihomo_release.download_mihomo("darwin-arm64", release="v1.19.31")
+ binary = self.binary_path()
+ self.assertFalse(binary.exists())
+ self.assertFalse(any(binary.parent.glob(".download-*")))
+
+ def test_http_redirect_downgrade_is_rejected(self):
+ for version in (True, False):
+ self.urlopen.side_effect = None
+ self.urlopen.return_value = Response(
+ b"v1.19.31" if version else archive_fixture(),
+ "http://example.com/download",
+ )
+ with self.subTest(version=version), self.assertRaises(RuntimeError):
+ if version:
+ mihomo_release.latest_release()
+ else:
+ mihomo_release.download_mihomo("darwin-arm64", release="v1.19.31")
+ self.assertFalse(self.binary_path().exists())
+
+ def test_interrupted_binary_publication_preserves_previous_binary(self):
+ binary = self.binary_path()
+ binary.parent.mkdir(parents=True)
+ binary.write_bytes(b"previous valid binary")
+ self.provide_archive(archive_fixture(contents=b"new binary"))
+ with (
+ patch.object(
+ mihomo_release.os, "replace", side_effect=OSError("publication failure")
+ ),
+ self.assertRaises(RuntimeError),
+ ):
+ mihomo_release.download_mihomo("darwin-arm64", release="v1.19.31")
+ self.assertEqual(binary.read_bytes(), b"previous valid binary")
+ self.assertEqual(list(binary.parent.iterdir()), [binary])
+ self.provide_archive(archive_fixture(contents=b"new binary"))
+ self.assertEqual(
+ mihomo_release.download_mihomo("darwin-arm64", release="v1.19.31"), binary
+ )
+ self.assertEqual(binary.read_bytes(), b"new binary")
+
+ def test_zip_rejects_traversal_and_non_regular_executables(self):
+ symlink = zipfile.ZipInfo("mihomo.exe")
+ symlink.create_system = 3
+ symlink.external_attr = (stat.S_IFLNK | 0o777) << 16
+ for name in ("../mihomo.exe", "/mihomo.exe", "..\\mihomo.exe", symlink):
+ archive = zip_contents([(name, b"outside")])
+ with self.subTest(name=str(name)):
+ self.assert_download_rejected(archive, "windows-amd64")
+ self.assertFalse((self.root.parent / "mihomo.exe").exists())
+
+ def test_zip_rejects_missing_or_multiple_executables(self):
+ for entries in (
+ [("readme.txt", b"no executable")],
+ [("mihomo.exe", b"first"), ("other.exe", b"second")],
+ ):
+ archive = zip_contents(entries)
+ with self.subTest(entries=entries):
+ self.assert_download_rejected(archive, "windows-amd64")
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/scripts/tests/test_native_release.py b/scripts/tests/test_native_release.py
new file mode 100644
index 0000000..af7c1a7
--- /dev/null
+++ b/scripts/tests/test_native_release.py
@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import hashlib
+import io
+import tarfile
+import tempfile
+import unittest
+import urllib.error
+import zipfile
+from pathlib import Path
+from unittest.mock import patch
+
+from vcore_scripts import native_release
+
+
+class Response(io.BytesIO):
+ def geturl(self):
+ return "https://release-assets.githubusercontent.com/fixture"
+
+
+class NativeReleaseTest(unittest.TestCase):
+ def test_ss_tar_is_bounded_named_only_and_rejects_links(self):
+ def archive(unsafe=False):
+ data = io.BytesIO()
+ with tarfile.open(fileobj=data, mode="w:xz") as bundle:
+ entry = tarfile.TarInfo("ssserver")
+ entry.size = 7
+ bundle.addfile(entry, io.BytesIO(b"fixture"))
+ entry = tarfile.TarInfo("sslocal")
+ if unsafe:
+ entry.type, entry.linkname = tarfile.SYMTYPE, "/tmp/forbidden"
+ bundle.addfile(entry)
+ return data.getvalue()
+
+ with tempfile.TemporaryDirectory() as directory:
+ path, binary = Path(directory) / "peer.tar.xz", Path(directory) / "ssserver"
+ path.write_bytes(archive())
+ self.assertEqual(
+ native_release._extract_tar(path, binary, "ssserver"),
+ hashlib.sha256(b"fixture").hexdigest(),
+ )
+ self.assertEqual(binary.read_bytes(), b"fixture")
+ path.write_bytes(archive(True))
+ with self.assertRaises(RuntimeError):
+ native_release._extract_tar(path, binary, "ssserver")
+
+ def test_foreign_binary_version_is_deferred_to_its_container(self):
+ archive = io.BytesIO()
+ with zipfile.ZipFile(archive, "w") as bundle:
+ bundle.writestr("v2ray", b"linux-fixture")
+ with (
+ tempfile.TemporaryDirectory() as directory,
+ patch("urllib.request.urlopen", return_value=Response(archive.getvalue())),
+ patch("vcore_scripts.native_release.run_command") as run,
+ ):
+ peer = native_release.download_native(
+ "V2", Path(directory), "linux-arm64", defer_version=True
+ )
+ run.assert_not_called()
+ self.assertIsNone(peer.identity["version"])
+ self.assertEqual(peer.binary.read_bytes(), b"linux-fixture")
+
+ def test_failed_download_never_uses_old_binary_or_leaks_network_details(self):
+ with (
+ tempfile.TemporaryDirectory() as directory,
+ patch(
+ "urllib.request.urlopen",
+ side_effect=urllib.error.URLError("synthetic-private-marker"),
+ ),
+ ):
+ binary = Path(directory) / "v2ray"
+ binary.write_bytes(b"older executable")
+ with self.assertRaises(RuntimeError) as caught:
+ native_release.download_native("V2", Path(directory), "darwin-arm64")
+ self.assertNotIn("synthetic-private-marker", str(caught.exception))
+ self.assertEqual(binary.read_bytes(), b"older executable")
+ self.assertEqual(list(Path(directory).iterdir()), [binary])
+
+ def test_v2ray_uses_latest_binary_and_records_content_identity(self):
+ archive = io.BytesIO()
+ with zipfile.ZipFile(archive, "w") as bundle:
+ bundle.writestr("v2ray", b"fixture-executable")
+ bundle.writestr("geoip.dat", b"unused")
+ with (
+ tempfile.TemporaryDirectory() as directory,
+ patch(
+ "urllib.request.urlopen", return_value=Response(archive.getvalue())
+ ) as request,
+ patch("vcore_scripts.native_release.run_command") as run,
+ ):
+ run.return_value.stdout = b"V2Ray 5.53.0 fixture\n"
+ run.return_value.returncode = 0
+ run.return_value.cleanup = True
+ peer = native_release.download_native("V2", Path(directory), "darwin-arm64")
+ self.assertEqual(
+ request.call_args.args[0].full_url,
+ "https://github.com/v2fly/v2ray-core/releases/latest/download/v2ray-macos-arm64-v8a.zip",
+ )
+ self.assertEqual(peer.binary.read_bytes(), b"fixture-executable")
+ self.assertEqual(
+ peer.identity["binary_sha256"],
+ hashlib.sha256(b"fixture-executable").hexdigest(),
+ )
+ self.assertEqual(
+ peer.identity["archive_sha256"],
+ hashlib.sha256(archive.getvalue()).hexdigest(),
+ )
+ self.assertEqual(peer.identity["version"], "V2Ray 5.53.0 fixture")
+ self.assertFalse((Path(directory) / "geoip.dat").exists())
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/scripts/tests/test_platform_delivery.py b/scripts/tests/test_platform_delivery.py
new file mode 100644
index 0000000..f5c1c6f
--- /dev/null
+++ b/scripts/tests/test_platform_delivery.py
@@ -0,0 +1,305 @@
+"""Offline delivery validation with real temporary output trees."""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+import os
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import patch
+
+from vcore_scripts import builds, platform_delivery
+from vcore_scripts.cli import main
+
+
+class PlatformDeliveryTest(unittest.TestCase):
+ def test_all_delivery_platforms_reject_linked_output_before_mutation(self):
+ for platform_name in ("apple", "windows", "android"):
+ relative = Path("dist") / platform_name
+ if platform_name == "windows":
+ relative /= "x64"
+ for depth in range(1, len(relative.parts) + 1):
+ with (
+ self.subTest(platform=platform_name, depth=depth),
+ tempfile.TemporaryDirectory() as directory,
+ ):
+ fixture = Path(directory)
+ root = fixture / "checkout"
+ root.mkdir()
+ external = fixture / "external"
+ external.mkdir()
+ link = root.joinpath(*relative.parts[:depth])
+ link.parent.mkdir(parents=True, exist_ok=True)
+ if os.name == "nt":
+ # Junctions need no symlink privilege on Windows CI.
+ subprocess.run(
+ ["cmd", "/c", "mklink", "/J", str(link), str(external)],
+ check=True,
+ capture_output=True,
+ )
+ else:
+ link.symlink_to(external, target_is_directory=True)
+ output = external.joinpath(*relative.parts[depth:])
+ output.mkdir(parents=True, exist_ok=True)
+ manifest = output / "vcore-delivery.json"
+ manifest.write_text("original manifest")
+ sentinel = output / "keep"
+ sentinel.write_bytes(b"original artifact")
+ ndk = fixture / "ndk"
+ ndk.mkdir()
+ (ndk / "source.properties").write_text("fixture")
+ with (
+ patch.dict(
+ os.environ, {"ANDROID_NDK_HOME": str(ndk)}, clear=True
+ ),
+ patch.object(Path, "home", return_value=fixture),
+ patch.object(
+ platform_delivery,
+ "os",
+ SimpleNamespace(
+ name="nt" if platform_name == "windows" else "posix",
+ environ=os.environ,
+ ),
+ ),
+ patch.object(builds, "CORE_DIR", root),
+ patch.object(
+ builds, "_windows_architecture", return_value="x64"
+ ),
+ patch.object(
+ builds, "_windows_msvc_environment", return_value={}
+ ),
+ patch.object(builds, "_android_toolchain", return_value=ndk),
+ patch.object(
+ platform_delivery, "_source", return_value={"fixture": True}
+ ),
+ patch.object(
+ platform_delivery, "_output", return_value="fixture"
+ ),
+ patch.object(
+ builds,
+ f"build_{platform_name}",
+ side_effect=AssertionError("unsafe path reached build"),
+ ) as build,
+ ):
+ try:
+ with self.assertRaisesRegex(ValueError, "symlink|reparse"):
+ platform_delivery.build_delivery(platform_name)
+ finally:
+ build.assert_not_called()
+ self.assertEqual(manifest.read_text(), "original manifest")
+ self.assertEqual(
+ sentinel.read_bytes(), b"original artifact"
+ )
+
+ def test_android_delivery_replaces_stale_abis_without_touching_other_outputs(self):
+ with tempfile.TemporaryDirectory() as directory:
+ root = Path(directory)
+ ndk = root / "ndk"
+ ndk.mkdir()
+ (ndk / "source.properties").write_text("Pkg.Revision = fixture")
+ output = root / "dist/android"
+ stale = output / "armeabi-v7a/libvcore.so"
+ stale.parent.mkdir(parents=True)
+ stale.write_bytes(b"stale")
+ (output / "vcore-delivery.json").write_text("old manifest")
+ unrelated = root / "dist/apple/keep"
+ unrelated.parent.mkdir(parents=True)
+ unrelated.write_bytes(b"keep")
+
+ def build():
+ self.assertFalse(stale.exists())
+ self.assertFalse((output / "vcore-delivery.json").exists())
+ for abi, machine in [("arm64-v8a", 183), ("x86_64", 62)]:
+ for name in ("libvcore.so", "libc++_shared.so"):
+ path = output / abi / name
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_bytes(
+ b"\x7fELF\x02\x01\x01"
+ + bytes(9)
+ + b"\x03\x00"
+ + machine.to_bytes(2, "little")
+ + builds.EXPECTED_IDENTITY
+ )
+
+ with (
+ patch.dict(os.environ, {"ANDROID_NDK_HOME": str(ndk)}, clear=True),
+ # Windows resolves home from environment variables that this
+ # hermetic fixture clears; do not depend on a runner profile.
+ patch.object(Path, "home", return_value=root),
+ patch.object(builds, "CORE_DIR", root),
+ patch.object(builds, "build_android", side_effect=build),
+ patch.object(builds, "_android_toolchain", return_value=ndk),
+ patch.object(
+ platform_delivery, "_source", return_value={"fixture": True}
+ ),
+ patch.object(platform_delivery, "_output", return_value="fixture"),
+ ):
+ platform_delivery.build_delivery("android")
+ platform_delivery.check_delivery([output / "vcore-delivery.json"])
+ self.assertEqual(unrelated.read_bytes(), b"keep")
+
+ def test_delivery_rejects_debug_before_starting_a_build(self):
+ with patch.dict(os.environ, {"VCORE_BUILD_PROFILE": "debug"}):
+ self.assertEqual(main(["build", "android", "--delivery"]), 1)
+
+ def test_android_evidence_checks_real_files_not_claimed_success(self):
+ with tempfile.TemporaryDirectory() as directory:
+ root = Path(directory)
+ source = root / "source"
+ source.mkdir()
+ (source / "Cargo.lock").write_bytes(b"fixture lock\n")
+ subprocess.run(["git", "init", "-q", str(source)], check=True)
+ subprocess.run(["git", "-C", str(source), "add", "."], check=True)
+ subprocess.run(
+ [
+ "git",
+ "-C",
+ str(source),
+ "-c",
+ "user.name=Fixture",
+ "-c",
+ "user.email=fixture@example.invalid",
+ "-c",
+ "commit.gpgsign=false",
+ "commit",
+ "-qm",
+ "fixture",
+ ],
+ check=True,
+ )
+
+ def git(ref):
+ return subprocess.check_output(
+ ["git", "-C", str(source), "rev-parse", ref], text=True
+ ).strip()
+
+ output = root / "android"
+ artifacts = []
+ identity = (
+ "VCore;engine=rust;coreVersion=0.1.0;"
+ "invokeApiVersion=5;configVersion=27"
+ )
+ for abi, machine in [("arm64-v8a", 183), ("x86_64", 62)]:
+ for name in ("libvcore.so", "libc++_shared.so"):
+ # Minimal ELF header, independent of the production reader.
+ contents = (
+ b"\x7fELF\x02\x01\x01"
+ + bytes(9)
+ + b"\x03\x00"
+ + machine.to_bytes(2, "little")
+ + bytes(44)
+ + identity.encode()
+ )
+ path = output / abi / name
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_bytes(contents)
+ artifacts.append(
+ {
+ "path": f"{abi}/{name}",
+ "size": len(contents),
+ "sha256": hashlib.sha256(contents).hexdigest(),
+ }
+ )
+ manifest = output / "vcore-delivery.json"
+ record = {
+ "formatVersion": 1,
+ "group": "android",
+ "profile": "release",
+ "source": {
+ "commit": git("HEAD"),
+ "tree": git("HEAD^{tree}"),
+ "lockSha256": hashlib.sha256(b"fixture lock\n").hexdigest(),
+ },
+ "buildIdentity": identity,
+ "features": [
+ "ffi",
+ "tun",
+ "inbound-http",
+ "inbound-socks5",
+ "outbound-anytls",
+ "outbound-socks5",
+ "outbound-shadowsocks",
+ "outbound-trojan",
+ "outbound-vmess",
+ "outbound-vless",
+ "outbound-hysteria2",
+ ],
+ "host": {"os": "Linux", "architecture": "x86_64"},
+ "toolchain": {
+ "rustc": "fixture",
+ "cargo": "fixture",
+ "ndk": "fixture",
+ "clang": "fixture",
+ "androidApi": "24",
+ },
+ "artifacts": artifacts,
+ }
+ manifest.write_text(json.dumps(record))
+ command = [
+ "check",
+ "platform-artifacts",
+ "--manifest",
+ str(manifest),
+ "--source-dir",
+ str(source),
+ ]
+ self.assertEqual(main(command), 0)
+ for mutation in (
+ "profile",
+ "features",
+ "identity",
+ "source",
+ "toolchain",
+ "empty",
+ "missing",
+ "duplicate",
+ "traversal",
+ "architecture",
+ ):
+ with self.subTest(mutation=mutation):
+ bad = copy.deepcopy(record)
+ if mutation == "profile":
+ bad["profile"] = "debug"
+ elif mutation == "features":
+ bad["features"].append("interop-test")
+ elif mutation == "identity":
+ bad["buildIdentity"] = "schema14"
+ elif mutation == "source":
+ bad["source"]["commit"] = "0" * 40
+ elif mutation == "toolchain":
+ del bad["toolchain"]["ndk"]
+ elif mutation == "empty":
+ bad["artifacts"] = []
+ elif mutation == "missing":
+ bad["artifacts"].pop()
+ elif mutation == "duplicate":
+ bad["artifacts"].append(bad["artifacts"][0])
+ elif mutation == "traversal":
+ bad["artifacts"][0]["path"] = "../android/arm64-v8a/libvcore.so"
+ elif mutation == "architecture":
+ file = output / "arm64-v8a/libvcore.so"
+ original = file.read_bytes()
+ wrong = original[:18] + b"\x3e\x00" + original[20:]
+ file.write_bytes(wrong)
+ bad["artifacts"][0]["sha256"] = hashlib.sha256(
+ wrong
+ ).hexdigest()
+ manifest.write_text(json.dumps(bad))
+ try:
+ self.assertEqual(main(command), 1)
+ finally:
+ if mutation == "architecture":
+ file.write_bytes(original)
+ manifest.write_text(json.dumps(record))
+ self.assertEqual(main(command + ["--complete"]), 1)
+ (output / "arm64-v8a/libc++_shared.so").unlink()
+ self.assertEqual(main(command), 1)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/scripts/tests/test_protocol_containers.py b/scripts/tests/test_protocol_containers.py
new file mode 100644
index 0000000..c0bb78b
--- /dev/null
+++ b/scripts/tests/test_protocol_containers.py
@@ -0,0 +1,281 @@
+"""Offline ownership/config checks; no server is launched on the host."""
+
+import contextlib
+import io
+import json
+import tempfile
+import unittest
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+from vcore_scripts.container_udp_origin import main as origin_main
+from vcore_scripts.container_udp_origin import serve as origin_serve
+from vcore_scripts.protocol_containers import NETWORK, ContainerLab, ContainerPeer
+from vcore_scripts.protocol_vmess_udp_ab import main, options
+from vcore_scripts.protocol_vmess_udp_container import client_config
+
+
+class ContainerTests(unittest.TestCase):
+ def test_frozen_latest_image_is_single_run_owned(self):
+ from vcore_scripts.protocol_containers import IMAGE, frozen_image
+
+ network = dict(
+ configuration=dict(mode="hostOnly", labels={"purpose": NETWORK}),
+ status=dict(ipv4Subnet="192.0.2.0/24", ipv6Subnet="fd00::/64"),
+ )
+ digest = "sha256:" + "a" * 64
+ inspection = dict(configuration=dict(descriptor=dict(digest=digest)))
+
+ def command(*args, **_):
+ return json.dumps([network if args[0] == "network" else inspection])
+
+ with (
+ tempfile.TemporaryDirectory() as root,
+ patch("vcore_scripts.protocol_containers.command", side_effect=command),
+ patch("vcore_scripts.protocol_containers.run_command") as pull,
+ ):
+ pull.return_value = SimpleNamespace(
+ returncode=0, cleanup=True, stdout=b"ok"
+ )
+ with frozen_image(Path(root) / "image.log") as snapshot:
+ first, second = ContainerLab({}), ContainerLab({})
+ self.assertEqual(first.image, second.image)
+ self.assertTrue(first.image.endswith("@" + digest))
+ self.assertEqual(snapshot["digest"], digest)
+ self.assertEqual(snapshot["tag"], IMAGE)
+ self.assertEqual(pull.call_count, 1)
+ ContainerLab({})
+ self.assertEqual(
+ pull.call_count, 2, "no image cache across independent runs"
+ )
+
+ def test_image_refresh_failure_never_falls_back_to_a_cached_image(self):
+ from vcore_scripts.protocol_containers import frozen_image
+
+ with (
+ tempfile.TemporaryDirectory() as root,
+ patch("vcore_scripts.protocol_containers.command") as inspect,
+ patch("vcore_scripts.protocol_containers.run_command") as pull,
+ ):
+ pull.return_value = SimpleNamespace(
+ returncode=1,
+ cleanup=True,
+ stdout=b"registry unavailable token=synthetic-secret",
+ )
+ log = Path(root) / "image.log"
+ with self.assertRaisesRegex(RuntimeError, "image pull"), frozen_image(log):
+ self.fail("failed refresh must not establish a frozen image scope")
+ inspect.assert_not_called()
+ self.assertIn("registry unavailable", log.read_text())
+ self.assertNotIn("synthetic-secret", log.read_text())
+
+ def test_dns_fixture_remains_owned_across_idle_business_phases(self):
+ control, udp = MagicMock(), MagicMock()
+ control.recv.return_value = b"\x11"
+ control.getsockname.return_value = ("192.0.2.55", 24000)
+ udp.getsockname.return_value = ("0.0.0.0", 53001)
+ query = b"\x00" * 12 + b"\x0dvcore-fixture\x04test\x00\x00\x01\x00\x01"
+ udp.recvfrom.return_value = (query, ("192.0.2.2", 40001))
+ udp.sendto.side_effect = lambda data, _peer: len(data)
+ with (
+ patch("vcore_scripts.container_udp_origin.socket.socket") as socket,
+ patch("vcore_scripts.container_udp_origin.SLOTS"),
+ patch(
+ "vcore_scripts.container_udp_origin.select.select",
+ side_effect=[
+ ([], [], []),
+ ([udp], [], []),
+ ([control], [], []),
+ ],
+ ),
+ ):
+ socket.return_value.__enter__.return_value = udp
+ origin_serve(control)
+ udp.sendto.assert_called_once()
+ self.assertEqual(udp.sendto.call_args.args[1], ("192.0.2.2", 40001))
+ with (
+ patch("vcore_scripts.container_udp_origin.socket.socket") as socket,
+ patch("vcore_scripts.container_udp_origin.SLOTS"),
+ patch(
+ "vcore_scripts.container_udp_origin.time.monotonic",
+ side_effect=[0, 241],
+ ),
+ patch("vcore_scripts.container_udp_origin.select.select") as wait,
+ ):
+ socket.return_value.__enter__.return_value = udp
+ origin_serve(control)
+ wait.assert_not_called()
+
+ def test_quic_mtu_applies_only_to_the_owned_guest_network(self):
+ lab = SimpleNamespace(
+ run_id="fixture", mtu=1500, image="fixture@sha256:synthetic"
+ )
+ peer = ContainerPeer(lab, Path("fixture"), "quic")
+ with (
+ patch(
+ "vcore_scripts.protocol_containers.command",
+ side_effect=RuntimeError("captured launch"),
+ ) as launch,
+ self.assertRaisesRegex(RuntimeError, "captured launch"),
+ ):
+ peer.start(["peer"])
+ arguments = launch.call_args.args
+ self.assertEqual(
+ arguments[arguments.index("--network") + 1], NETWORK + ",mtu=1500"
+ )
+ self.assertNotIn("--cap-add", arguments)
+ self.assertNotIn("--publish", arguments)
+
+ def test_long_roles_keep_bounded_distinct_owned_container_names(self):
+ lab = SimpleNamespace(run_id="0123456789ab")
+ roles = [
+ "xhttp-stream-up-download-reality-tls-origin",
+ "xhttp-stream-up-download-reality-tls-server",
+ "xhttp-stream-up-download-reality-tls-upstream",
+ ]
+ peers = [ContainerPeer(lab, Path("fixture"), role) for role in roles]
+ self.assertEqual(len({peer.name for peer in peers}), len(roles))
+ for peer, role in zip(peers, roles, strict=True):
+ self.assertLessEqual(len(peer.name), 63)
+ self.assertIn(lab.run_id, peer.name)
+ self.assertEqual(peer.record["role"], role)
+
+ def test_non_private_network_fails_before_image_or_launch(self):
+ network = dict(configuration=dict(mode="shared", labels={"purpose": NETWORK}))
+ with (
+ patch(
+ "vcore_scripts.protocol_containers.command",
+ return_value=json.dumps([network]),
+ ) as command,
+ self.assertRaisesRegex(RuntimeError, "host-only"),
+ ):
+ ContainerLab({})
+ command.assert_called_once_with("network", "inspect", NETWORK)
+
+ def test_ownership_mismatch_never_deletes(self):
+ lab = SimpleNamespace(run_id="fixture")
+ with tempfile.TemporaryDirectory() as root:
+ peer = ContainerPeer(lab, Path(root), "server")
+ unrelated = dict(
+ id=peer.name, configuration=dict(labels={"purpose": "other"})
+ )
+ with (
+ patch(
+ "vcore_scripts.protocol_containers.listing",
+ return_value=[unrelated],
+ ),
+ patch("vcore_scripts.protocol_containers.command") as command,
+ self.assertRaisesRegex(RuntimeError, "ownership"),
+ ):
+ peer.stop()
+ command.assert_not_called()
+
+ def test_inventory_failure_still_closes_log_capture(self):
+ for error in [
+ RuntimeError("isolated container operation failed: list"),
+ TimeoutError("inventory query timed out"),
+ json.JSONDecodeError("invalid inventory", "not-json", 0),
+ KeyboardInterrupt(),
+ ]:
+ with self.subTest(error=type(error).__name__):
+ peer = ContainerPeer(
+ SimpleNamespace(run_id="fixture"), Path("fixture"), "server"
+ )
+ peer.capture = MagicMock(record={"joined": True})
+ with (
+ patch(
+ "vcore_scripts.protocol_containers.listing", side_effect=error
+ ) as listing,
+ patch("vcore_scripts.protocol_containers.command") as command,
+ self.assertRaises(type(error)) as raised,
+ ):
+ peer.stop()
+ self.assertIs(raised.exception, error)
+ peer.capture.__exit__.assert_called_once_with(None, None, None)
+ self.assertTrue(peer.record["log_cleanup"])
+ self.assertFalse(peer.record["joined"])
+ listing.assert_called_once_with()
+ command.assert_not_called()
+
+ def test_cleanup_only_owned_vm_and_verifies_absence(self):
+ lab = SimpleNamespace(run_id="fixture")
+ with tempfile.TemporaryDirectory() as root:
+ peer = ContainerPeer(lab, Path(root), "server")
+ owned = dict(
+ id=peer.name,
+ configuration=dict(labels={"purpose": NETWORK, "vcore-run": "fixture"}),
+ status=dict(state="running"),
+ )
+ other = dict(id="another-task")
+ with (
+ patch(
+ "vcore_scripts.protocol_containers.listing",
+ side_effect=[[owned, other], [other]],
+ ),
+ patch("vcore_scripts.protocol_containers.command") as command,
+ ):
+ peer.stop()
+ self.assertEqual(
+ [call.args for call in command.call_args_list],
+ [
+ ("stop", "--time", "5", peer.name),
+ ("delete", "--force", peer.name),
+ ],
+ )
+ self.assertTrue(peer.record["joined"])
+
+ def test_failed_launch_still_registers_cleanup(self):
+ lab = ContainerLab.__new__(ContainerLab)
+ lab.run_id, lab.record = "fixture", {"peers": []}
+ with (
+ patch.object(
+ ContainerPeer, "start", side_effect=RuntimeError("partial launch")
+ ),
+ patch.object(ContainerPeer, "stop") as stop,
+ ):
+ with (
+ self.assertRaisesRegex(RuntimeError, "partial launch"),
+ contextlib.ExitStack() as stack,
+ ):
+ lab.start(stack, Path("fixture"), "server", [])
+ stop.assert_called_once()
+
+ def test_no_native_origin_entry_or_archived_host_probe(self):
+ with (
+ patch.dict("os.environ", {}, clear=True),
+ self.assertRaisesRegex(SystemExit, "container harness"),
+ ):
+ origin_main()
+ for option in ["--collision-probe", "--socket-probe"]:
+ with (
+ patch("sys.argv", ["diagnostic", "unused", option]),
+ contextlib.redirect_stderr(io.StringIO()),
+ ):
+ with self.assertRaises(SystemExit) as error:
+ main()
+ self.assertEqual(error.exception.code, 2)
+
+ def test_client_server_and_origins_use_distinct_container_addresses(self):
+ config, selected = client_config(
+ options(["raw", "xudp", "packetaddr"]),
+ "ws",
+ True,
+ "192.0.2.2",
+ "192.0.2.3",
+ "192.0.2.4",
+ "fixture-pin",
+ )
+ self.assertEqual(len(selected), 39)
+ self.assertEqual({item["socks_host"] for item in selected}, {"192.0.2.4"})
+ self.assertEqual(
+ {item["listen"] for item in config["listeners"]}, {"192.0.2.4"}
+ )
+ self.assertEqual({item["server"] for item in config["proxies"]}, {"192.0.2.2"})
+ self.assertEqual(config["hosts"]["vcore-fixture.test"], "192.0.2.3")
+ self.assertEqual(config["rules"], ["MATCH,REJECT"])
+ self.assertNotIn("packet-encoding", config["proxies"][0])
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/scripts/tests/test_protocol_evidence.py b/scripts/tests/test_protocol_evidence.py
new file mode 100644
index 0000000..4291ff9
--- /dev/null
+++ b/scripts/tests/test_protocol_evidence.py
@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+import copy
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+from vcore_scripts.protocol_evidence import (
+ load_manifest,
+ rust_results,
+ select_cases,
+ validate_results,
+)
+
+
+class ProtocolEvidenceTest(unittest.TestCase):
+ def setUp(self):
+ self.cases = select_cases(load_manifest(), stage="FOUNDATIONS")
+ self.results = [
+ {
+ "case_id": case["case_id"],
+ "status": "PASS",
+ "scope": "foundation-only",
+ "assertions": dict.fromkeys(case["expected_observation"], True),
+ "evidence": list(case["required_evidence"]),
+ "cleanup": True,
+ "command_exit_code": 0,
+ "row_ids": case["row_ids"],
+ "peer_kind": case["peer_kind"],
+ }
+ for case in self.cases
+ ]
+
+ def test_complete_results_are_accepted_as_foundation_not_protocol_field_signoff(
+ self,
+ ):
+ validate_results(self.cases, self.results)
+
+ def test_missing_duplicate_unknown_and_empty_required_cases_fail(self):
+ for results in [
+ self.results[:-1],
+ self.results + [self.results[0]],
+ self.results + [{"case_id": "unknown"}],
+ ]:
+ with self.subTest(results=len(results)), self.assertRaises(ValueError):
+ validate_results(self.cases, results)
+ with self.assertRaises(ValueError):
+ validate_results([], [])
+ with self.assertRaises(ValueError):
+ select_cases(load_manifest(), stage="WIREGUARD")
+
+ def test_failure_blocked_not_run_timeout_and_cleanup_never_become_pass(self):
+ for update in [
+ {"status": status} for status in ["FAIL", "BLOCKED", "NOT RUN"]
+ ] + [{"cleanup": False}, {"command_exit_code": 124}]:
+ results = copy.deepcopy(self.results)
+ results[0].update(update)
+ with self.subTest(update=update), self.assertRaises(ValueError):
+ validate_results(self.cases, results)
+
+ def test_cfg_only_incomplete_or_false_assertions_are_not_behavior_evidence(self):
+ for update in [
+ {"evidence": ["CFG"]},
+ {"assertions": {}},
+ {"assertions": {key: False for key in self.results[0]["assertions"]}},
+ {"row_ids": ["T08"]},
+ ]:
+ results = copy.deepcopy(self.results)
+ results[0].update(update)
+ with self.subTest(update=update), self.assertRaises(ValueError):
+ validate_results(self.cases, results)
+
+ def test_manifest_rejects_duplicate_ids_and_unknown_rows(self):
+ manifest = load_manifest()
+ for mutation in ["duplicate", "unknown-row"]:
+ data = {
+ "schema_version": 1,
+ "kind": "executable-case-manifest",
+ "cases": copy.deepcopy(manifest),
+ }
+ if mutation == "duplicate":
+ data["cases"].append(data["cases"][0])
+ else:
+ data["cases"][0]["row_ids"] = ["not-a-field"]
+ with tempfile.TemporaryDirectory() as directory:
+ path = Path(directory) / "cases.json"
+ path.write_text(json.dumps(data))
+ with self.assertRaises(ValueError):
+ load_manifest(path)
+
+ def test_resource_claims_require_idle_structured_snapshots(self):
+ case = next(
+ case for case in self.cases if case["case_id"] == "FOUNDATIONS-RESOURCES"
+ )
+ events = [
+ {
+ "schema_version": 1,
+ "suite": case["case_id"],
+ "assertion": name,
+ "status": status,
+ }
+ for name in case["expected_observation"]
+ for status in ["BEGIN", "PASS"]
+ ]
+ self.assertEqual(rust_results(case, events, 0)["status"], "FAIL")
+
+ def test_malformed_or_unknown_assertions_never_become_pass(self):
+ case = self.cases[0]
+ events = [
+ {
+ "schema_version": 1,
+ "suite": case["case_id"],
+ "assertion": name,
+ "status": status,
+ }
+ for name in case["expected_observation"]
+ for status in ["BEGIN", "PASS"]
+ ]
+ self.assertEqual(rust_results(case, events, 0)["status"], "PASS")
+ events[0]["schema_version"] = 99
+ self.assertEqual(rust_results(case, events, 0)["status"], "FAIL")
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/scripts/tests/test_protocol_harness.py b/scripts/tests/test_protocol_harness.py
new file mode 100644
index 0000000..437459b
--- /dev/null
+++ b/scripts/tests/test_protocol_harness.py
@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+from vcore_scripts import cli, protocol_harness, protocol_preflight
+from vcore_scripts.native_release import PeerArtifact
+from vcore_scripts.protocol_inputs import redact
+
+
+class ProtocolHarnessTest(unittest.TestCase):
+ def test_cli_freezes_list_case_protocol_and_preflight_selection(self):
+ with patch("vcore_scripts.cli.run_protocol_interop") as run:
+ self.assertEqual(
+ cli.main(
+ [
+ "check",
+ "protocol-interop",
+ "--suite",
+ "foundations",
+ "--case",
+ "FOUNDATIONS-QUIC",
+ "--protocol",
+ "foundation",
+ "--list",
+ ]
+ ),
+ 0,
+ )
+ self.assertEqual(run.call_args.kwargs["identifiers"], ["FOUNDATIONS-QUIC"])
+ self.assertTrue(run.call_args.kwargs["list_only"])
+ with contextlib.redirect_stderr(io.StringIO()), self.assertRaises(SystemExit):
+ cli.main(
+ [
+ "check",
+ "protocol-interop",
+ "--suite",
+ "foundations",
+ "--list",
+ "--preflight",
+ ]
+ )
+
+ def test_coverage_requires_explicit_catalog_or_result_mode(self):
+ with contextlib.redirect_stderr(io.StringIO()), self.assertRaises(SystemExit):
+ cli.main(["check", "protocol-coverage"])
+ with patch("vcore_scripts.cli.check_run") as check:
+ self.assertEqual(
+ cli.main(
+ [
+ "check",
+ "protocol-coverage",
+ "--suite",
+ "foundations",
+ "--run-dir",
+ "target/interop/runs/fixture",
+ ]
+ ),
+ 0,
+ )
+ self.assertEqual(check.call_args.args[1], "FOUNDATIONS")
+ self.assertEqual(
+ check.call_args.args[0],
+ Path("target/interop/runs/fixture").resolve(),
+ )
+
+ def test_redaction_removes_paths_uuid_authorization_and_private_key(self):
+ output = redact(
+ "/Users/example/private/input password=secret "
+ "Authorization: Bearer secret-token\n"
+ "12345678-1234-1234-1234-123456789abc "
+ "-----BEGIN PRIVATE KEY-----secret-material-----END PRIVATE KEY-----"
+ )
+ for secret in [
+ "secret",
+ "Bearer-token",
+ "secret-token",
+ "12345678",
+ "/Users/example",
+ "secret-material",
+ ]:
+ self.assertNotIn(secret, output)
+
+ def test_peer_preflight_failure_does_not_prevent_other_peer_capabilities(self):
+ with tempfile.TemporaryDirectory() as temporary:
+
+ def download(kind, directory):
+ if kind == "H":
+ raise RuntimeError("private-marker")
+ return PeerArtifact(
+ Path(temporary) / kind, {"version": "fixture", "kind": kind}
+ )
+
+ with patch.object(
+ protocol_preflight, "download_native", side_effect=download
+ ):
+ artifacts, records = protocol_preflight.preflight(
+ Path(temporary), {"H", "XR", "V2"}
+ )
+ self.assertEqual(set(artifacts), {"XR", "V2"})
+ self.assertEqual(
+ {record["kind"]: record["status"] for record in records},
+ {"H": "BLOCKED", "V2": "READY", "XR": "READY"},
+ )
+ self.assertNotIn("private-marker", json.dumps(records))
+
+ def test_sigint_still_writes_incomplete_report_without_promoting_not_run(self):
+ identity = {
+ "source_tree_sha256": "0" * 64,
+ "lock_sha256": "1" * 64,
+ "dirty_patch_sha256": "2" * 64,
+ "parent_commit": "3" * 40,
+ }
+ with (
+ tempfile.TemporaryDirectory() as temporary,
+ contextlib.ExitStack() as stack,
+ ):
+ root = Path(temporary)
+ stack.enter_context(patch.object(protocol_harness, "CORE_DIR", root))
+ stack.enter_context(
+ patch.object(
+ protocol_harness,
+ "run_identity",
+ return_value=identity
+ | {
+ "stage": "VMESS",
+ "mode": "execute",
+ "suite_timeout_seconds": 30,
+ "commands": [],
+ },
+ )
+ )
+ stack.enter_context(
+ patch.object(protocol_harness, "source_identity", return_value=identity)
+ )
+ stack.enter_context(
+ patch.object(
+ protocol_harness,
+ "exclusive_run",
+ side_effect=contextlib.nullcontext,
+ )
+ )
+ stack.enter_context(
+ patch.object(protocol_harness, "check_protocol_catalogs")
+ )
+ stack.enter_context(
+ patch(
+ "vcore_scripts.protocol_vmess_acceptance.execute",
+ side_effect=KeyboardInterrupt,
+ )
+ )
+ output = root / "target/interop/runs/fixture"
+ with (
+ contextlib.redirect_stdout(io.StringIO()),
+ self.assertRaises(RuntimeError),
+ ):
+ protocol_harness.run_protocol_interop(
+ stage="VMESS", identifiers=["VMESS-CFG"], run_dir=output
+ )
+ self.assertEqual(
+ json.loads((output / "cases.json").read_text())[0]["status"], "NOT RUN"
+ )
+ self.assertFalse(json.loads((output / "run.json").read_text())["cleanup"])
+ self.assertTrue((output / "resources.jsonl").is_file())
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/scripts/tests/test_protocol_hysteria2.py b/scripts/tests/test_protocol_hysteria2.py
new file mode 100644
index 0000000..0f55c04
--- /dev/null
+++ b/scripts/tests/test_protocol_hysteria2.py
@@ -0,0 +1,157 @@
+"""Offline checks of HYSTERIA2's evidence boundary; no sockets or protocol peers."""
+
+import copy
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+from vcore_scripts.protocol_hysteria2 import test_command
+from vcore_scripts.protocol_hysteria2_acceptance import (
+ bandwidth_pass,
+ hopping_pass,
+ native_result,
+)
+from vcore_scripts.protocol_hysteria2_catalog import (
+ FIELDS,
+ H,
+ definitions,
+ events_pass,
+)
+
+
+def pair(suite, assertion):
+ return [
+ dict(schema_version=1, suite=suite, assertion=assertion, status=s)
+ for s in ("BEGIN", "PASS")
+ ]
+
+
+def tcp_events():
+ outer = pair("HYSTERIA2-BASE", "tcp_ipv4_ipv6_domain_and_measure")
+ return (
+ outer[:1] + pair("HYSTERIA2-BASE", "tcp_10mib_both_directions") * 3 + outer[1:]
+ )
+
+
+class Hysteria2AcceptanceTest(unittest.TestCase):
+ def test_catalog_covers_all_fields_and_eight_hop_combinations(self):
+ cases = definitions()
+ self.assertEqual(len(cases), 36)
+ self.assertEqual(len(cases), len({c["case_id"] for c in cases}))
+ self.assertEqual(len(FIELDS), 20)
+ self.assertEqual(FIELDS, set().union(*(set(c["row_ids"]) for c in cases)))
+ self.assertEqual(
+ {
+ (v["ipv6"], v["obfs"], v["random_interval"])
+ for v in H.values()
+ if v["test"] == "native_hopping"
+ },
+ {
+ (a, b, c)
+ for a in (False, True)
+ for b in (False, True)
+ for c in (False, True)
+ },
+ )
+
+ def test_partial_unknown_duplicate_and_wrong_suite_events_fail(self):
+ # The public caller records one outer case plus three nested bulk
+ # transfers. Mirror that real trace, not only its outer success event.
+ observed = tcp_events()
+ self.assertTrue(events_pass(observed, "hysteria2_tcp_base"))
+ wrong = copy.deepcopy(observed)
+ wrong[1]["suite"] = "XHTTP-BASE"
+ for bad in (
+ [],
+ observed[:1],
+ observed * 2,
+ wrong,
+ observed + pair("HYSTERIA2-BASE", "unknown"),
+ pair("HYSTERIA2-BASE", "tcp_ipv4_ipv6_domain_and_measure"),
+ observed[:1] + observed[3:],
+ observed + pair("HYSTERIA2-BASE", "tcp_10mib_both_directions"),
+ ):
+ self.assertFalse(events_pass(bad, "hysteria2_tcp_base"))
+
+ def test_native_identity_cleanup_or_missing_results_fail(self):
+ case = next(c for c in definitions() if c["case_id"] == "HYSTERIA2-TCP")
+ test = "hysteria2_tcp_base"
+ report = dict(
+ status="PASS",
+ cleanup=True,
+ source_unchanged=True,
+ obfs=False,
+ cases=[
+ dict(
+ case_id=test,
+ status="PASS",
+ exit_code=0,
+ command_cleanup=True,
+ command=test_command(test),
+ )
+ ],
+ isolation=dict(
+ network_mode="hostOnly",
+ host_servers=False,
+ guest_mtu=1500,
+ image_digest="sha256:" + "a" * 64,
+ peers=[dict(started=True, joined=True)],
+ ),
+ peers={
+ "M": dict(
+ version="test",
+ binary_sha256="b" * 64,
+ source_url="https://github.com/MetaCubeX/mihomo/"
+ "releases/download/test/fixture",
+ )
+ },
+ )
+ with tempfile.TemporaryDirectory() as temporary:
+ directory = Path(temporary)
+ path = directory / f"{test}-events.jsonl"
+ path.write_text("".join(json.dumps(e) + "\n" for e in tcp_events()))
+ self.assertEqual(native_result(case, report, directory)["status"], "PASS")
+ for key, bad in (
+ ("peers", {}),
+ ("cleanup", False),
+ ("cases", []),
+ ("source_unchanged", False),
+ ):
+ altered = copy.deepcopy(report)
+ altered[key] = bad
+ self.assertEqual(
+ native_result(case, altered, directory)["status"], "FAIL"
+ )
+ path.unlink()
+ self.assertEqual(native_result(case, report, directory)["status"], "FAIL")
+
+ def test_bandwidth_and_hop_counters_cannot_be_forged_as_empty_success(self):
+ self.assertFalse(bandwidth_pass([]))
+ self.assertFalse(bandwidth_pass([{}] * 10))
+ self.assertFalse(hopping_pass({}))
+ hop = dict(
+ seconds=60,
+ protected_sockets=9,
+ tcp_bytes_per_direction=10485760,
+ tcp_sha256="c" * 64,
+ udp_packets=1500,
+ udp_target_kinds=3,
+ udp_maximums=[4071, 4052, 4060],
+ socket_peak=2,
+ )
+ self.assertTrue(hopping_pass(hop))
+ for key, value in (
+ ("seconds", 59),
+ ("protected_sockets", 8),
+ ("udp_packets", 0),
+ ("tcp_sha256", ""),
+ ("socket_peak", 3),
+ ("udp_maximums", []),
+ ):
+ altered = dict(hop, **{key: value})
+ self.assertFalse(hopping_pass(altered))
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/scripts/tests/test_protocol_integration.py b/scripts/tests/test_protocol_integration.py
new file mode 100644
index 0000000..2edc642
--- /dev/null
+++ b/scripts/tests/test_protocol_integration.py
@@ -0,0 +1,334 @@
+from __future__ import annotations
+
+import copy
+import io
+import json
+import tempfile
+import unittest
+from contextlib import redirect_stdout
+from pathlib import Path
+
+from vcore_scripts import cli
+
+
+class IntegrationAcceptanceTest(unittest.TestCase):
+ def test_native_source_identity_and_cleanup_are_required(self):
+ from vcore_scripts.protocol_integration_checks import envelope
+
+ identity = dict(
+ version="official-test",
+ binary_sha256="a" * 64,
+ archive_sha256="b" * 64,
+ source_url="https://github.com/MetaCubeX/mihomo/releases/latest/download/test",
+ )
+ source = {
+ k: "c" * 64
+ for k in (
+ "parent_commit",
+ "source_tree_sha256",
+ "dirty_patch_sha256",
+ "lock_sha256",
+ )
+ }
+ digest = "sha256:" + "d" * 64
+ report = dict(
+ status="PASS",
+ cleanup=True,
+ source_unchanged=True,
+ source=source,
+ peers={"M": identity},
+ isolation=dict(
+ network_mode="hostOnly",
+ host_servers=False,
+ guest_mtu=1500,
+ image_digest=digest,
+ peers=[dict(started=True, joined=True)],
+ ),
+ )
+ self.assertTrue(envelope(report, {"M": identity}, source, digest))
+ for mutate in (
+ lambda d: d.update(cleanup=False),
+ lambda d: d.update(source_unchanged=False),
+ lambda d: d["source"].update(source_tree_sha256="e" * 64),
+ lambda d: d["peers"]["M"].update(binary_sha256="e" * 64),
+ lambda d: d["isolation"].update(host_servers=True),
+ lambda d: d["isolation"].update(guest_mtu=1200),
+ lambda d: d["isolation"]["peers"][0].update(joined=False),
+ lambda d: d["isolation"].update(peers=[]),
+ ):
+ broken = copy.deepcopy(report)
+ mutate(broken)
+ self.assertFalse(envelope(broken, {"M": identity}, source, digest))
+
+ def test_pressure_evidence_is_recomputed_not_inferred(self):
+ from vcore_scripts.protocol_evidence import RESOURCE_KINDS
+ from vcore_scripts.protocol_integration_metrics import (
+ NEW,
+ QUEUES,
+ lifetimes,
+ rebuild,
+ soak,
+ )
+
+ def snapshot(current):
+ return dict(
+ counts=[
+ dict(kind=k, current=current, peak=1)
+ for k in sorted(RESOURCE_KINDS)
+ ]
+ )
+
+ def sample(active=True):
+ return dict(
+ heap_in_use=2_000_000,
+ rss_kib=50_000,
+ fd=100 if active else 6,
+ resources=snapshot(int(active)),
+ queues=[dict(kind=k, capacity=v, peak=1) for k, v in QUEUES.items()],
+ )
+
+ event = dict(resources=snapshot(0))
+ stop = dict(
+ stop_ms=4,
+ after_stop=sample(False),
+ quiet_seconds=5.1,
+ quiet=sample(False),
+ ports_rebound=True,
+ )
+ rows = [
+ dict(
+ generation=i,
+ tcp=20,
+ udp=20,
+ per_protocol_tcp=5,
+ per_protocol_udp=5,
+ active=sample(),
+ setup_us=[1000] * 40,
+ fault="owned-peer-connections-closed",
+ new_clients=True,
+ after_clients=sample(),
+ )
+ for i in range(100)
+ ]
+ value = dict(
+ count=100,
+ same_running_session=True,
+ protocols=NEW,
+ cold_fd=4,
+ baseline_fd=6,
+ cycles=rows,
+ stopped=stop,
+ )
+ self.assertTrue(rebuild(value, event))
+ for mutate in (
+ lambda d: d["cycles"].pop(),
+ lambda d: d.update(same_running_session=False),
+ lambda d: d["cycles"][0].update(tcp=0),
+ lambda d: d["cycles"][0].update(setup_us=[]),
+ lambda d: d["stopped"].update(stop_ms=5001),
+ lambda d: d["stopped"].update(quiet_seconds=0),
+ lambda d: d["stopped"]["after_stop"].update(fd=7),
+ ):
+ broken = copy.deepcopy(value)
+ mutate(broken)
+ self.assertFalse(rebuild(broken, event))
+ self.assertFalse(lifetimes(dict(count=99, cycles=[]), []))
+ points = [
+ dict(sample(), seconds=300 + i * 60, waves=i + 1, faults=5 + i)
+ for i in range(25)
+ ]
+ value = dict(
+ requested_seconds=1800,
+ seconds=1800.2,
+ protocols=NEW,
+ tcp=20,
+ udp=20,
+ per_protocol_tcp=5,
+ per_protocol_udp=5,
+ waves=1000,
+ normal_verified_bytes=1000 * 20 * 2 * 2 * 257,
+ normal_corruption=0,
+ normal_misdirection=0,
+ normal_unexpected_loss=0,
+ switches=list(range(1, 1800)),
+ faults=[
+ dict(
+ start=60 * i,
+ end=60 * i + 0.5,
+ old_tcp_closed=20,
+ new_tcp=20,
+ new_udp=20,
+ replay=False,
+ )
+ for i in range(1, 30)
+ ],
+ samples=points,
+ cold_fd=4,
+ baseline_fd=6,
+ stopped=stop,
+ active_end=sample(),
+ first_setup_us=[1000] * 40,
+ last_setup_us=[1100] * 40,
+ first_setup_median_us=1000,
+ last_setup_median_us=1100,
+ heap=dict(
+ early_median=2_000_000, late_median=2_000_000, allowed_growth=1048576
+ ),
+ )
+ self.assertTrue(soak(value, event, points))
+ for mutate in (
+ lambda d: d.update(requested_seconds=65),
+ lambda d: d.update(seconds=1799),
+ lambda d: d["faults"].pop(),
+ lambda d: d.update(switches=[]),
+ lambda d: d["samples"][0].update(heap_in_use=0),
+ lambda d: d["samples"][-1]["queues"][0].update(peak=10000),
+ lambda d: d["heap"].update(late_median=4_000_000),
+ lambda d: d.update(last_setup_us=[3000] * 40, last_setup_median_us=3000),
+ lambda d: d.update(normal_unexpected_loss=1),
+ ):
+ broken = copy.deepcopy(value)
+ mutate(broken)
+ self.assertFalse(soak(broken, event, broken["samples"]))
+ self.assertFalse(soak(value, event, points[:-1]))
+
+ def test_integration_consumer_results_keep_the_manifest_scope(self):
+ from vcore_scripts.protocol_evidence import load_manifest, validate_results
+ from vcore_scripts.protocol_security_acceptance import result
+
+ case = next(
+ c for c in load_manifest() if c["case_id"] == "INTEGRATION-PAIR-SS-SS"
+ )
+ validate_results([case], [result(case, True, True)])
+
+ def test_pair_evidence_requires_each_real_path_and_original_assertions(self):
+ from vcore_scripts.protocol_integration_acceptance import pair_pass
+ from vcore_scripts.protocol_integration_native import rust_command
+
+ identifier = "INTEGRATION-PAIR-SOCKS5-VLESS"
+ record = dict(
+ case_id=identifier,
+ command=rust_command(),
+ exit_code=0,
+ command_cleanup=True,
+ )
+ paths = [
+ dict(
+ outer_ipv6=v6,
+ nested_select=group,
+ tcp_target_kinds=3,
+ tcp_bytes_each_direction=31457280,
+ udp_target_kinds=3,
+ udp_packets=1200,
+ udp_sizes=[1, 64, 512, 1200],
+ server_first=True,
+ client_first=True,
+ ports_rebound=True,
+ )
+ for v6 in (False, True)
+ for group in (False, True)
+ ]
+ observation = dict(
+ first="socks5",
+ last="vless",
+ paths=paths,
+ domain_native=[],
+ budgets=[
+ dict(
+ transmit=tx,
+ receive=rx,
+ roundtrip_size=min(tx, rx),
+ packets=100,
+ oversize_rejected_before_origin=True,
+ )
+ for tx, rx in ((128, 128), (512, 256))
+ ],
+ routed_udp=dict(
+ upstream_business_udp_disabled=True,
+ carrier_tcp=True,
+ carrier_udp=True,
+ leaf_business_udp_rejected=True,
+ ),
+ carrier_capability=dict(
+ upstream_datagrams="rejected",
+ tcp_allowed=True,
+ udp_allowed=True,
+ no_bypass=True,
+ ),
+ )
+ events = [
+ dict(schema_version=1, suite=suite, assertion=assertion, status=status)
+ for suite, assertion, count in (
+ ("INTEGRATION-PAIR", "ordered_pair", 1),
+ ("INTEGRATION-BASE", "tcp_10mib_both_directions", 12),
+ ("INTEGRATION-PAIR", "directional_budget", 1),
+ ("INTEGRATION-PAIR", "routed_udp_permission", 1),
+ ("INTEGRATION-PAIR", "carrier_capability", 1),
+ )
+ for _ in range(count)
+ for status in ("BEGIN", "PASS")
+ ]
+ with tempfile.TemporaryDirectory() as temp:
+ root = Path(temp)
+ event_path = root / (identifier + "-events.jsonl")
+ data_path = root / (identifier + "-observations.json")
+ event_path.write_text("".join(json.dumps(e) + "\n" for e in events))
+ data_path.write_text(json.dumps(observation))
+ self.assertTrue(pair_pass(identifier, record, root))
+ for mutate in (
+ lambda d: d["paths"].pop(),
+ lambda d: d["paths"].append(d["paths"][0]),
+ lambda d: d["paths"][0].update(udp_packets=799),
+ lambda d: d["paths"][0].update(ports_rebound=False),
+ lambda d: d.update(last="vmess"),
+ lambda d: d["budgets"][0].update(packets=99),
+ lambda d: d["carrier_capability"].update(no_bypass=False),
+ ):
+ broken = copy.deepcopy(observation)
+ mutate(broken)
+ data_path.write_text(json.dumps(broken))
+ self.assertFalse(pair_pass(identifier, record, root))
+ data_path.write_text(json.dumps(observation))
+ event_path.write_text("".join(json.dumps(e) + "\n" for e in events[:-1]))
+ self.assertFalse(pair_pass(identifier, record, root))
+
+ def test_list_contains_all_ordered_pairs_and_remaining_gates(self):
+ output = io.StringIO()
+ with redirect_stdout(output):
+ self.assertEqual(
+ cli.main(
+ ["check", "protocol-interop", "--suite", "integration", "--list"]
+ ),
+ 0,
+ )
+ identifiers = [line.split("\t")[0] for line in output.getvalue().splitlines()]
+ protocols = {"SOCKS5", "ANYTLS", "SS", "TROJAN", "VMESS", "VLESS", "HYSTERIA2"}
+ expected = {
+ f"INTEGRATION-PAIR-{first}-{last}"
+ for first in protocols
+ for last in protocols
+ }
+ self.assertEqual(len(expected), 49)
+ self.assertEqual({key for key in identifiers if "-PAIR-" in key}, expected)
+ self.assertEqual(len(identifiers), len(set(identifiers)))
+ self.assertTrue(
+ {
+ "INTEGRATION-ENTRYPOINTS",
+ "INTEGRATION-GRAPH",
+ "INTEGRATION-DNS-MEASURE",
+ "INTEGRATION-SS-ALGORITHMS",
+ "INTEGRATION-SS-EIH",
+ "INTEGRATION-LIFECYCLE",
+ "INTEGRATION-REBUILD",
+ "INTEGRATION-FAILURES",
+ "INTEGRATION-SOAK",
+ "INTEGRATION-HY2-HOP",
+ "INTEGRATION-DEBUG",
+ "INTEGRATION-RELEASE",
+ "INTEGRATION-QUALITY",
+ "INTEGRATION-FEATURES",
+ "INTEGRATION-SCRIPTS",
+ "INTEGRATION-SHARED",
+ }
+ <= set(identifiers)
+ )
diff --git a/scripts/tests/test_protocol_peers.py b/scripts/tests/test_protocol_peers.py
new file mode 100644
index 0000000..597531b
--- /dev/null
+++ b/scripts/tests/test_protocol_peers.py
@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import os
+import select
+import signal
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+from vcore_scripts.protocol_peers import OwnedProcess, run_command
+
+
+class OwnedPeerTest(unittest.TestCase):
+ def test_success_is_bounded_and_records_exit_and_cleanup(self):
+ result = run_command([sys.executable, "-c", "print('fixture')"], timeout=2)
+ self.assertEqual(result.stdout, b"fixture\n")
+ self.assertEqual(result.returncode, 0)
+ self.assertTrue(result.cleanup)
+
+ def test_timeout_and_output_overflow_fail_and_join(self):
+ for source, limit in [
+ ("import time; time.sleep(60)", 128),
+ ("print('x'*10000)", 64),
+ ]:
+ result = run_command(
+ [sys.executable, "-c", source], timeout=0.2, limit=limit
+ )
+ self.assertNotEqual(result.returncode, 0)
+ self.assertTrue(result.cleanup)
+ self.assertLessEqual(len(result.stdout), limit)
+
+ def test_partial_start_and_permission_failure_do_not_leave_a_process(self):
+ from unittest.mock import patch
+
+ for error in [FileNotFoundError(), PermissionError()]:
+ with (
+ tempfile.TemporaryDirectory() as directory,
+ patch("subprocess.Popen", side_effect=error),
+ ):
+ record = {}
+ with (
+ self.assertRaises(type(error)),
+ OwnedProcess(["fixture"], Path(directory) / "private.log", record),
+ ):
+ pass
+ self.assertTrue(record["joined"])
+ self.assertFalse(record["started"])
+
+ def test_peer_exit_is_not_readiness(self):
+ with tempfile.TemporaryDirectory() as directory:
+ record = {}
+ with OwnedProcess(
+ [sys.executable, "-c", "raise SystemExit(3)"],
+ Path(directory) / "private.log",
+ record,
+ ) as peer:
+ peer.process.wait(timeout=2)
+ with self.assertRaises(RuntimeError):
+ peer.ensure_alive()
+ self.assertEqual(record["unexpected_exit"], 3)
+ self.assertTrue(record["joined"])
+
+ def test_cleanup_failure_is_explicit(self):
+ from unittest.mock import patch
+
+ with tempfile.TemporaryDirectory() as directory:
+ record = {}
+ peer = OwnedProcess(
+ [sys.executable, "-c", "import time; time.sleep(60)"],
+ Path(directory) / "private.log",
+ record,
+ )
+ peer.__enter__()
+ try:
+ with (
+ patch.object(
+ peer,
+ "_terminate",
+ side_effect=OSError("synthetic-private-marker"),
+ ),
+ self.assertRaises(OSError),
+ ):
+ peer.__exit__(None, None, None)
+ self.assertFalse(record["joined"])
+ finally:
+ peer._terminate()
+ peer._finish_reader()
+
+ def test_cancellation_joins_only_the_owned_peer(self):
+ with tempfile.TemporaryDirectory() as directory:
+ record = {}
+ with (
+ self.assertRaises(KeyboardInterrupt),
+ OwnedProcess(
+ [sys.executable, "-c", "import time; time.sleep(60)"],
+ Path(directory) / "peer.log",
+ record,
+ ) as peer,
+ ):
+ pid = peer.process.pid
+ raise KeyboardInterrupt
+ self.assertTrue(record["joined"])
+ self.assertIsNotNone(peer.process.poll())
+ with self.assertRaises(ProcessLookupError):
+ os.kill(pid, 0)
+
+ @unittest.skipIf(os.name == "nt", "Unix process-group signal contract")
+ def test_real_sigint_joins_nested_peer_without_stopping_unrelated_peer(self):
+ with tempfile.TemporaryDirectory() as directory:
+ source = (
+ "import signal, sys\nfrom pathlib import Path\n"
+ "from vcore_scripts.protocol_peers import OwnedProcess\n"
+ "with OwnedProcess([sys.executable, '-c', "
+ "'import time; time.sleep(60)'], "
+ "Path(sys.argv[1]), {}) as peer:\n"
+ " print(peer.process.pid, flush=True)\n signal.pause()\n"
+ )
+ unrelated = {}
+ with OwnedProcess(
+ [sys.executable, "-c", "import time; time.sleep(60)"],
+ Path(directory) / "unrelated.log",
+ unrelated,
+ ) as sentinel:
+ worker = subprocess.Popen(
+ [sys.executable, "-c", source, str(Path(directory) / "nested.log")],
+ stdout=subprocess.PIPE,
+ stderr=subprocess.DEVNULL,
+ start_new_session=True,
+ )
+ try:
+ ready, _, _ = select.select([worker.stdout], [], [], 5)
+ self.assertTrue(ready, "signal fixture did not start")
+ pid = int(worker.stdout.readline())
+ worker.send_signal(signal.SIGINT)
+ self.assertNotEqual(worker.wait(timeout=10), 0)
+ with self.assertRaises(ProcessLookupError):
+ os.kill(pid, 0)
+ sentinel.ensure_alive()
+ finally:
+ if worker.poll() is None:
+ worker.kill()
+ worker.wait(timeout=5)
+ worker.stdout.close()
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/scripts/tests/test_protocol_reality_hybrid.py b/scripts/tests/test_protocol_reality_hybrid.py
new file mode 100644
index 0000000..ef13861
--- /dev/null
+++ b/scripts/tests/test_protocol_reality_hybrid.py
@@ -0,0 +1,125 @@
+import unittest
+
+from vcore_scripts.cli import _parser
+from vcore_scripts.protocol_reality_hybrid import (
+ MODES,
+ cases,
+ negative_wire_pass,
+ wire_pass,
+)
+
+
+class HybridRealityGateTests(unittest.TestCase):
+ def test_browser_downgrade_and_retry_require_each_legs_actual_server_hello(self):
+ events = []
+ for port, group, hrr in ((25002, 29, False), (25003, 24, True)):
+ events.extend(
+ [
+ {
+ "port": port,
+ "event": "client-hello",
+ "shares": [[4588, 1216], [29, 32]],
+ "groups": [4588, 29, 23, 24],
+ },
+ {"port": port, "event": "server-hello", "group": group, "hrr": hrr},
+ ]
+ )
+ self.assertTrue(negative_wire_pass(events, "chrome"))
+ self.assertTrue(negative_wire_pass(events * 2, "chrome", legs=2))
+ self.assertFalse(negative_wire_pass(events, "chrome", legs=2))
+ self.assertFalse(negative_wire_pass(events[:-1], "chrome"))
+ self.assertFalse(
+ negative_wire_pass(events[:-1] + [dict(events[-1], hrr=False)], "chrome")
+ )
+ self.assertFalse(
+ negative_wire_pass(
+ [dict(events[0], shares=[[29, 32]])] + events[1:], "chrome"
+ )
+ )
+
+ def test_hybrid_only_peer_rejection_needs_positive_no_shared_group_evidence(self):
+ events = []
+ for front, cover in ((25002, 24432), (25003, 24433)):
+ events.extend(
+ [
+ {
+ "port": front,
+ "event": "client-hello",
+ "shares": [[4588, 1216]],
+ "groups": [4588],
+ },
+ {"port": cover, "event": "no-shared-group"},
+ {"port": front, "event": "server-close", "bytes": 0},
+ ]
+ )
+ self.assertTrue(negative_wire_pass(events, "none"))
+ self.assertFalse(negative_wire_pass(events[:-1], "none"))
+ self.assertFalse(negative_wire_pass(events, "none", legs=2))
+ self.assertFalse(negative_wire_pass(events, "chrome"))
+ self.assertFalse(
+ negative_wire_pass(
+ events + [{"port": 25002, "event": "server-hello", "group": 29}],
+ "none",
+ )
+ )
+
+ def test_required_scope_includes_profiles_download_and_lifecycle(self):
+ required = cases()
+ self.assertEqual(len(required), 54)
+ self.assertEqual(len(MODES), 12)
+ for profile in ("none", "chrome"):
+ for version in ("h1", "h2"):
+ for mode in ("stream-up", "packet-up"):
+ self.assertIn(f"{profile}-{version}-{mode}-base", required)
+ for variant in ("main-classic", "download-classic"):
+ self.assertIn(f"{profile}-{version}-{variant}", required)
+ self.assertIn(f"{profile}-{version}-stream-up-security", required)
+ for mode in ("tcp", "grpc", "vision", "h2-stream-up"):
+ for test in ("life", "owned"):
+ self.assertIn(f"chrome-{mode}-{test}", required)
+
+ def test_observation_requires_both_real_shares_and_actual_negotiation(self):
+ events = [
+ {
+ "port": 25000,
+ "event": "client-hello",
+ "shares": [[4588, 1216], [29, 32]],
+ },
+ {"port": 25000, "event": "server-hello", "group": 4588},
+ ]
+ expected = {25000: (True, "chrome")}
+ self.assertTrue(wire_pass(events, expected))
+ self.assertFalse(wire_pass(events[:1], expected))
+ self.assertFalse(wire_pass(events[1:], expected))
+ self.assertFalse(wire_pass(events, {**expected, 25001: (True, "chrome")}))
+ self.assertFalse(wire_pass(events + [dict(events[1], group=29)], expected))
+ self.assertFalse(
+ wire_pass([dict(events[0], shares=[[29, 32]]), events[1]], expected)
+ )
+
+ def test_classic_and_hybrid_legs_have_independent_requirements(self):
+ events = [
+ {"port": 25000, "event": "client-hello", "shares": [[4588, 1216]]},
+ {"port": 25000, "event": "server-hello", "group": 4588},
+ {"port": 25001, "event": "client-hello", "shares": [[29, 32]]},
+ {"port": 25001, "event": "server-hello", "group": 29},
+ ]
+ self.assertTrue(
+ wire_pass(events, {25000: (True, "none"), 25001: (False, "chrome")})
+ )
+ self.assertFalse(
+ wire_pass(events, {25000: (True, "none"), 25001: (True, "chrome")})
+ )
+
+ def test_cli_exposes_a_subpackage_not_full_stage_acceptance(self):
+ args = _parser().parse_args(
+ [
+ "check",
+ "reality-hybrid",
+ "--run-dir",
+ "target/interop/runs/new",
+ "--case",
+ "chrome-tcp-base",
+ ]
+ )
+ self.assertEqual(args.identifiers, ["chrome-tcp-base"])
diff --git a/scripts/tests/test_protocol_retirement.py b/scripts/tests/test_protocol_retirement.py
new file mode 100644
index 0000000..f40e653
--- /dev/null
+++ b/scripts/tests/test_protocol_retirement.py
@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import io
+import tempfile
+import tomllib
+import unittest
+from contextlib import redirect_stderr
+from pathlib import Path
+from unittest.mock import patch
+
+from vcore_scripts import cli
+from vcore_scripts.protocol_catalogs import FIELD_IDS, PEERS, PROTOCOLS, SUITES
+from vcore_scripts.protocol_preflight import preflight
+
+
+class ProtocolRetirementTest(unittest.TestCase):
+ def test_wireguard_is_not_a_feature_protocol_peer_or_field_target(self):
+ root = Path(__file__).resolve().parents[2]
+ features = tomllib.loads((root / "Cargo.toml").read_text())["features"]
+ self.assertNotIn("outbound-wireguard", features)
+ self.assertNotIn("wireguard", PROTOCOLS)
+ self.assertNotIn("W", PEERS)
+ self.assertNotIn("WIREGUARD", SUITES)
+ self.assertFalse(any(identifier.startswith("WG") for identifier in FIELD_IDS))
+
+ def test_retired_cli_selections_fail_before_any_harness_work(self):
+ for arguments in (
+ ["protocol-interop", "--suite", "wireguard", "--list"],
+ ["protocol-coverage", "--suite", "wireguard", "--catalog-only"],
+ [
+ "protocol-interop",
+ "--suite",
+ "security",
+ "--protocol",
+ "wireguard",
+ "--list",
+ ],
+ ):
+ with self.subTest(arguments=arguments), redirect_stderr(io.StringIO()):
+ with self.assertRaises(SystemExit) as error:
+ cli.main(["check", *arguments])
+ self.assertEqual(error.exception.code, 2)
+
+ def test_retired_peer_preflight_cannot_download_or_create_a_container(self):
+ with tempfile.TemporaryDirectory() as temporary:
+ directory = Path(temporary) / "not-created"
+ with (
+ patch("vcore_scripts.protocol_preflight.run_command") as command,
+ patch("vcore_scripts.protocol_preflight.download_native") as download,
+ ):
+ with self.assertRaisesRegex(ValueError, "unsupported native peer"):
+ preflight(directory, {"M", "W"}, container=True)
+ command.assert_not_called()
+ download.assert_not_called()
+ self.assertFalse(directory.exists())
diff --git a/scripts/tests/test_protocol_run_evidence.py b/scripts/tests/test_protocol_run_evidence.py
new file mode 100644
index 0000000..0370ee6
--- /dev/null
+++ b/scripts/tests/test_protocol_run_evidence.py
@@ -0,0 +1,235 @@
+"""Offline evidence fixtures; these synthetic passes are never stage reports."""
+
+from __future__ import annotations
+
+import contextlib
+import copy
+import hashlib
+import io
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+from vcore_scripts.protocol_evidence import RESOURCE_KINDS, check_run, load_manifest
+from vcore_scripts.protocol_harness import SCRIPT_OBSERVATIONS
+
+
+class RunEvidenceTest(unittest.TestCase):
+ def fixture(self):
+ cases = [case for case in load_manifest() if case["stage"] == "FOUNDATIONS"]
+ idle = {
+ "counts": [
+ {"kind": name, "current": 0, "peak": 1}
+ for name in sorted(RESOURCE_KINDS)
+ ]
+ }
+ events = []
+ legacy = []
+ native = []
+ results = []
+ for case in cases:
+ results.append(
+ {
+ "case_id": case["case_id"],
+ "row_ids": case["row_ids"],
+ "peer_kind": case["peer_kind"],
+ "scope": "foundation-only",
+ "status": "PASS",
+ "cleanup": True,
+ "command_exit_code": 0,
+ "assertions": dict.fromkeys(case["expected_observation"], True),
+ "evidence": case["required_evidence"],
+ }
+ )
+ if case["runner"] in {"rust", "mihomo-legacy"}:
+ target = legacy if case["runner"] == "mihomo-legacy" else events
+ for assertion in case["expected_observation"]:
+ for status in ["BEGIN", "PASS"]:
+ target.append(
+ {
+ "schema_version": 1,
+ "suite": case["case_id"],
+ "assertion": assertion,
+ "status": status,
+ "seconds": 5,
+ "resources": idle
+ if case["case_id"] == "FOUNDATIONS-RESOURCES"
+ and status == "PASS"
+ else None,
+ "checkpoints": [
+ {"phase": phase, "resources": idle}
+ for phase in ["baseline", "after-stop", "quiet"]
+ ],
+ }
+ )
+ if case["runner"] == "native-stream":
+ native.append(
+ {
+ "case_id": case["case_id"],
+ "status": "PASS",
+ "cleanup": {"joined": True},
+ "command_exit_code": 0,
+ "rust_event": {
+ "server_first": True,
+ "payload_bytes": 65536,
+ "tail_bytes": 14,
+ "protect_calls": 1,
+ "driver_joined": True,
+ "resources_idle": True,
+ "resources": idle,
+ },
+ "origin": {
+ "finished": True,
+ "accepted": 1,
+ "received": 65536,
+ "failed": False,
+ },
+ }
+ )
+ peers = [
+ {
+ "kind": kind,
+ "status": "READY",
+ "version": "offline-fixture",
+ "source_url": "https://github.com/fixture/project/releases/latest/download/fixture",
+ "archive_sha256": "0" * 64,
+ "binary_sha256": "1" * 64,
+ "release": "fixture",
+ "container_status": "READY",
+ "container_artifact": {"binary_sha256": "2" * 64, "release": "fixture"},
+ }
+ for kind in ["M", "V2"]
+ ]
+ commands = [
+ "rust-foundations",
+ "native-probe-build",
+ "legacy-mihomo",
+ "offline-scripts",
+ "feature-default",
+ "feature-minimal",
+ "feature-outbound-trojan",
+ "feature-outbound-vmess",
+ "feature-outbound-hysteria2",
+ "feature-stream-transport",
+ "feature-quic-transport",
+ ]
+ return {
+ "run.json": {
+ "stage": "FOUNDATIONS",
+ "mode": "execute",
+ "source_unchanged": True,
+ "cleanup": True,
+ "selected_cases": [case["case_id"] for case in cases],
+ "source_tree_sha256": "0" * 64,
+ "lock_sha256": "1" * 64,
+ "dirty_patch_sha256": "2" * 64,
+ "commands": [
+ {"name": name, "exit_code": 0, "cleanup": True} for name in commands
+ ],
+ },
+ "cases.json": results,
+ "peers.json": peers,
+ "rust-events.jsonl": events,
+ "legacy-events.jsonl": legacy,
+ "resources.jsonl": [{"resources": idle}],
+ "summary.md": "Offline fixture only",
+ "native/stream-cases.json": {
+ "cases": native,
+ "cleanup": True,
+ "peers": peers,
+ "abnormal_cleanup": {
+ "passed": True,
+ "kind": "M",
+ "failure_injected": True,
+ "joined": True,
+ "port_rebound": True,
+ },
+ },
+ "script-tests.json": {
+ "tests_run": len(set(SCRIPT_OBSERVATIONS.values())),
+ "cases": [
+ {"test": name, "status": "PASS"}
+ for name in sorted(set(SCRIPT_OBSERVATIONS.values()))
+ ],
+ },
+ }
+
+ def write_fixture(self, directory, data):
+ artifacts = []
+ for name, value in data.items():
+ if name == "run.json":
+ continue
+ path = directory / name
+ path.parent.mkdir(parents=True, exist_ok=True)
+ text = (
+ "".join(json.dumps(item) + "\n" for item in value)
+ if name.endswith(".jsonl")
+ else value
+ if name.endswith(".md")
+ else json.dumps(value)
+ )
+ path.write_text(text)
+ artifacts.append(
+ {"path": name, "sha256": hashlib.sha256(path.read_bytes()).hexdigest()}
+ )
+ (directory / "run.json").write_text(
+ json.dumps(data["run.json"] | {"artifacts": artifacts})
+ )
+
+ def test_complete_original_evidence_is_required_even_when_summary_claims_pass(self):
+ fixture = self.fixture()
+ with (
+ tempfile.TemporaryDirectory() as temporary,
+ contextlib.redirect_stdout(io.StringIO()),
+ ):
+ directory = Path(temporary)
+ self.write_fixture(directory, fixture)
+ check_run(directory, "FOUNDATIONS")
+ for mutation in [
+ "raw-event",
+ "nonidle",
+ "command",
+ "peer",
+ "artifact",
+ "quiet",
+ "script",
+ ]:
+ data = copy.deepcopy(fixture)
+ if mutation == "raw-event":
+ data["rust-events.jsonl"][1]["status"] = "FAIL"
+ elif mutation == "nonidle":
+ data["resources.jsonl"][0]["resources"]["counts"][0]["current"] = 1
+ elif mutation == "command":
+ data["run.json"]["commands"][0]["exit_code"] = 124
+ elif mutation == "peer":
+ data["peers.json"][0]["status"] = "BLOCKED"
+ elif mutation == "artifact":
+ del data["rust-events.jsonl"]
+ elif mutation == "quiet":
+ for event in data["rust-events.jsonl"]:
+ if event["suite"] == "FOUNDATIONS-RESOURCES":
+ event["checkpoints"] = []
+ else:
+ data["script-tests.json"]["cases"][0]["status"] = "NOT RUN"
+ self.write_fixture(directory, data)
+ with self.subTest(mutation=mutation), self.assertRaises(ValueError):
+ check_run(directory, "FOUNDATIONS")
+
+ def test_content_tampering_partial_runs_and_preflight_cannot_sign_off(self):
+ with tempfile.TemporaryDirectory() as temporary:
+ directory = Path(temporary)
+ data = self.fixture()
+ self.write_fixture(directory, data)
+ (directory / "summary.md").write_text("tampered")
+ with self.assertRaises(ValueError):
+ check_run(directory, "FOUNDATIONS")
+ for change in [
+ {"selected_cases": []},
+ {"mode": "preflight"},
+ {"source_unchanged": False},
+ ]:
+ data["run.json"].update(change)
+ self.write_fixture(directory, data)
+ with self.assertRaises(ValueError):
+ check_run(directory, "FOUNDATIONS")
diff --git a/scripts/tests/test_protocol_security.py b/scripts/tests/test_protocol_security.py
new file mode 100644
index 0000000..3f845da
--- /dev/null
+++ b/scripts/tests/test_protocol_security.py
@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+import copy
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+from vcore_scripts.protocol_evidence import load_manifest
+from vcore_scripts.protocol_security_acceptance import (
+ gate_result,
+ native_envelope,
+ rust_command,
+ vless_pass,
+)
+from vcore_scripts.protocol_security_catalog import FIELDS, definitions, groups
+
+
+class SecurityAcceptanceTest(unittest.TestCase):
+ def test_legacy_ech_gateway_keeps_response_inside_tls(self):
+ from vcore_scripts.protocol_ech import legacy_gateway_command
+
+ self.assertEqual(
+ legacy_gateway_command(),
+ [
+ "env",
+ "XRAY_BUF_SPLICE=disable",
+ "/data/fixture/peer",
+ "run",
+ "-c",
+ "/data/fixture/config.json",
+ ],
+ )
+
+ def test_frozen_scope_and_compositions(self):
+ cases = definitions()
+ self.assertEqual(
+ [c for c in load_manifest() if c["stage"] == "SECURITY"], cases
+ )
+ self.assertEqual(len(cases), 43)
+ self.assertEqual(set().union(*(set(c["row_ids"]) for c in cases)), FIELDS)
+ self.assertEqual(len(FIELDS), 11)
+ catalog = groups()
+ self.assertEqual(len(catalog["SECURITY-ECH-STANDARD"]["selected"]), 50)
+ for profile in ("chrome", "chrome120", "firefox", "safari"):
+ self.assertEqual(
+ catalog["SECURITY-ECH-" + profile.upper()]["client_fingerprint"],
+ profile,
+ )
+ for security in ("ECH", "JLS", "HYBRID"):
+ self.assertEqual(
+ sum(k.startswith(f"SECURITY-{security}-ENCRYPTION-") for k in catalog),
+ 6,
+ )
+ self.assertFalse(
+ any("shadow" in str(c).lower() or "restls" in str(c).lower() for c in cases)
+ )
+
+ def fixture(self, directory):
+ name, test = "SECURITY-ECH-TCP-TLS-REJECT", "native_ech_fail_closed"
+ group = dict(runner="vless", selected=[name], ech=True)
+ report = dict(
+ status="PASS",
+ cleanup=True,
+ source_unchanged=True,
+ source=dict(
+ parent_commit="7" * 40,
+ source_tree_sha256="a" * 64,
+ dirty_patch_sha256="b" * 64,
+ lock_sha256="c" * 64,
+ ),
+ ech=True,
+ jls=False,
+ encryption_profile=None,
+ client_fingerprint=None,
+ cases=[
+ dict(
+ case_id=name,
+ command=rust_command("vless_native", test),
+ exit_code=0,
+ cleanup=True,
+ command_cleanup=True,
+ status="PASS",
+ peer_kind="M",
+ )
+ ],
+ isolation=dict(
+ network_mode="hostOnly",
+ host_servers=False,
+ guest_mtu=1500,
+ image_digest="sha256:" + "d" * 64,
+ peers=[dict(started=True, joined=True)],
+ ),
+ peers={
+ "M": dict(
+ version="synthetic test metadata",
+ binary_sha256="a" * 64,
+ archive_sha256="b" * 64,
+ source_url="https://github.com/MetaCubeX/mihomo/releases/latest/download/fixture",
+ )
+ },
+ )
+ path = directory / (name + "-events.jsonl")
+ events = [
+ dict(schema_version=1, suite="SECURITY-WIRE", assertion=test, status=s)
+ for s in ("BEGIN", "PASS")
+ ]
+ path.write_text("".join(json.dumps(e) + "\n" for e in events))
+ return group, report, path, events
+
+ def test_native_missing_duplicate_wrong_events_fail(self):
+ with tempfile.TemporaryDirectory() as temp:
+ directory = Path(temp)
+ group, report, path, events = self.fixture(directory)
+ self.assertTrue(vless_pass(group, report, directory))
+ for samples in ([], report["cases"] * 2):
+ invalid = dict(report, cases=samples)
+ self.assertFalse(vless_pass(group, invalid, directory))
+ for samples in (
+ events[:1],
+ events * 2,
+ [dict(e, suite="VLESS-WIRE") for e in events],
+ [dict(e, status="PASS") for e in events],
+ ):
+ path.write_text("".join(json.dumps(e) + "\n" for e in samples))
+ self.assertFalse(vless_pass(group, report, directory))
+
+ def test_source_cleanup_and_identity_are_not_inferred(self):
+ with tempfile.TemporaryDirectory() as temp:
+ _, report, _, _ = self.fixture(Path(temp))
+ self.assertTrue(native_envelope(report, report["peers"], report["source"]))
+ self.assertTrue(native_envelope(report, image_digest="sha256:" + "d" * 64))
+ self.assertFalse(native_envelope(report, image_digest="sha256:" + "e" * 64))
+ for field in ("cleanup", "source_unchanged"):
+ self.assertFalse(native_envelope(dict(report, **{field: False})))
+ self.assertFalse(native_envelope(report, {}, report["source"]))
+ self.assertFalse(native_envelope(report, report["peers"], {}))
+ for mutate in (
+ lambda r: r["isolation"].update(host_servers=True),
+ lambda r: r["isolation"].update(peers=[]),
+ lambda r: r["isolation"]["peers"][0].update(joined=False),
+ lambda r: r["peers"]["M"].update(binary_sha256=""),
+ ):
+ invalid = copy.deepcopy(report)
+ mutate(invalid)
+ self.assertFalse(native_envelope(invalid))
+
+ def test_close_reference_cannot_hide_a_different_official_profile(self):
+ with tempfile.TemporaryDirectory() as temp:
+ directory = Path(temp)
+ group, report, _, _ = self.fixture(directory)
+ name, test = "SECURITY-ECH-GRPC-TLS-CLOSE", "native_mihomo_close_alignment"
+ group.update(selected=[name], client_fingerprint="safari")
+ report.update(client_fingerprint="safari")
+ report["cases"][0].update(
+ case_id=name, command=rust_command("vless_native", test)
+ )
+ (directory / (name + "-events.jsonl")).write_text(
+ "".join(
+ json.dumps(
+ dict(
+ schema_version=1,
+ suite="SECURITY-WIRE",
+ assertion=test,
+ status=s,
+ )
+ )
+ + "\n"
+ for s in ("BEGIN", "PASS")
+ )
+ )
+ path = directory / "grpc-tls-tls-close-reference.json"
+ self.assertFalse(vless_pass(group, report, directory))
+ valid = dict(
+ scope="ech-safari-chrome-baseline",
+ client_fingerprint="chrome",
+ dut_client_fingerprint="safari",
+ terminated=True,
+ tail_hex="",
+ )
+ path.write_text(json.dumps(valid))
+ self.assertTrue(vless_pass(group, report, directory))
+ for field, value in (
+ ("scope", "same-mode"),
+ ("client_fingerprint", "safari"),
+ ("dut_client_fingerprint", "chrome"),
+ ("terminated", False),
+ ):
+ path.write_text(json.dumps(dict(valid, **{field: value})))
+ self.assertFalse(vless_pass(group, report, directory))
+
+ def test_empty_gate_and_missing_script_proof_fail(self):
+ cases = {c["case_id"]: c for c in definitions()}
+ for name in ("SECURITY-CFG", "SECURITY-RELEASE", "SECURITY-SCRIPTS"):
+ self.assertEqual(gate_result(cases[name], [], [])["status"], "FAIL")
+ record = [dict(exit_code=0, cleanup=True)]
+ self.assertEqual(
+ gate_result(cases["SECURITY-CFG"], record, [])["status"], "FAIL"
+ )
+ self.assertEqual(
+ gate_result(cases["SECURITY-SCRIPTS"], record, [], {})["status"], "FAIL"
+ )
diff --git a/scripts/tests/test_protocol_trojan.py b/scripts/tests/test_protocol_trojan.py
new file mode 100644
index 0000000..bc76938
--- /dev/null
+++ b/scripts/tests/test_protocol_trojan.py
@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import copy
+import json
+import tempfile
+import tomllib
+import unittest
+from pathlib import Path
+
+from vcore_scripts.builds import CORE_DIR, DEFAULT_FEATURES
+from vcore_scripts.protocol_evidence import load_manifest, select_cases
+from vcore_scripts.protocol_trojan import CASES, native_events_pass
+from vcore_scripts.protocol_trojan_acceptance import fields_report, native_results
+
+
+class TrojanEvidenceTest(unittest.TestCase):
+ def test_removed_or_downgraded_required_case_is_rejected(self):
+ original = load_manifest()
+ index = next(i for i, case in enumerate(original) if case["stage"] == "TROJAN")
+ for downgrade in (True, False):
+ cases = copy.deepcopy(original)
+ if downgrade:
+ cases[index]["required"] = False
+ else:
+ cases.pop(index)
+ with tempfile.TemporaryDirectory() as directory:
+ path = Path(directory) / "cases.json"
+ path.write_text(
+ json.dumps(
+ {
+ "schema_version": 1,
+ "kind": "executable-case-manifest",
+ "cases": cases,
+ }
+ )
+ )
+ with self.assertRaises(ValueError):
+ load_manifest(path)
+
+ def test_native_summary_cannot_hide_missing_events_or_unjoined_processes(self):
+ case = next(
+ case for case in load_manifest() if case["case_id"] == "TROJAN-M-TCP"
+ )
+ record = {
+ "case_id": case["case_id"],
+ "status": "PASS",
+ "mode": "tcp",
+ "exit_code": 0,
+ "command_cleanup": True,
+ "cleanup": {"joined": True},
+ }
+ report = {"source_unchanged": True, "cases": [record]}
+ with tempfile.TemporaryDirectory() as directory:
+ root = Path(directory)
+ self.assertEqual(native_results([case], report, root)[0]["status"], "FAIL")
+ events = [
+ {
+ "suite": "TROJAN-NATIVE",
+ "assertion": "public_trojan_native_base",
+ "schema_version": 1,
+ "status": status,
+ }
+ for status in ("BEGIN", "PASS")
+ ]
+ (root / (case["case_id"] + "-events.jsonl")).write_text(
+ "".join(json.dumps(event) + "\n" for event in events)
+ )
+ self.assertEqual(native_results([case], report, root)[0]["status"], "PASS")
+ for update in [
+ {"exit_code": 124},
+ {"command_cleanup": False},
+ {"cleanup": {"joined": False}},
+ {"status": "BLOCKED"},
+ ]:
+ invalid = copy.deepcopy(report)
+ invalid["cases"][0].update(update)
+ self.assertEqual(
+ native_results([case], invalid, root)[0]["status"], "FAIL"
+ )
+ report["source_unchanged"] = False
+ self.assertEqual(native_results([case], report, root)[0]["status"], "FAIL")
+ report["cases"].append(record)
+ with self.assertRaises(ValueError):
+ native_results([case], report, root)
+
+ def test_partial_case_selection_never_signs_off_fields(self):
+ case = next(case for case in load_manifest() if case["case_id"] == "TROJAN-CFG")
+ result = fields_report([case], [{"case_id": case["case_id"], "status": "PASS"}])
+ self.assertEqual(len(result["fields"]), 18)
+ self.assertTrue(all(field["status"] == "NOT RUN" for field in result["fields"]))
+
+ def test_default_and_packaged_builds_enable_trojan(self):
+ features = tomllib.loads((CORE_DIR / "Cargo.toml").read_text())["features"]
+ self.assertIn("outbound-trojan", features["default"])
+ self.assertIn("outbound-trojan", features["tun"])
+ self.assertIn("outbound-trojan", DEFAULT_FEATURES.split(","))
+
+ def test_every_native_case_is_required_and_mapped_to_fields(self):
+ cases = select_cases(load_manifest(), stage="TROJAN")
+ native = {
+ case["case_id"]: case for case in cases if case["runner"] == "native-trojan"
+ }
+ self.assertEqual(set(native), set(CASES))
+ for identifier, (kind, mode, test) in CASES.items():
+ self.assertEqual(native[identifier]["peer_kind"], kind)
+ self.assertEqual(
+ native[identifier]["peer_config"], {"mode": mode, "test": test}
+ )
+ self.assertTrue(native[identifier]["row_ids"])
+ if kind != "M":
+ self.assertTrue(native[identifier]["gap_source"])
+
+ def test_zero_tests_partial_duplicate_wrong_or_failed_events_fail(self):
+ test = "public_trojan_native_base"
+ events = [
+ {
+ "suite": "TROJAN-NATIVE",
+ "assertion": test,
+ "schema_version": 1,
+ "status": status,
+ }
+ for status in ("BEGIN", "PASS")
+ ]
+ self.assertTrue(native_events_pass(events, test))
+ for invalid in [[], events[:1], events + events, events[::-1]]:
+ self.assertFalse(native_events_pass(invalid, test))
+ for update in [
+ {"status": "FAIL"},
+ {"assertion": "other"},
+ {"schema_version": 2},
+ ]:
+ invalid = copy.deepcopy(events)
+ invalid[1].update(update)
+ self.assertFalse(native_events_pass(invalid, test))
+
+ def test_lifecycle_requires_twenty_full_quiet_cycles(self):
+ test = "runtime::public_trojan_native_lifecycle"
+ events = [
+ {
+ "suite": "TROJAN-NATIVE",
+ "assertion": test,
+ "schema_version": 1,
+ "status": status,
+ }
+ for status in ("BEGIN", "PASS")
+ ]
+ cycles = [
+ {
+ "suite": "TROJAN-LIFE-CYCLE",
+ "assertion": "stop_and_remain_quiet",
+ "schema_version": 1,
+ "status": status,
+ "seconds": 5.1 if status == "PASS" else 0,
+ }
+ for _ in range(20)
+ for status in ("BEGIN", "PASS")
+ ]
+ self.assertTrue(native_events_pass(events + cycles, test))
+ self.assertFalse(native_events_pass(events + cycles[:-2], test))
+ cycles[-1]["seconds"] = 4.9
+ self.assertFalse(native_events_pass(events + cycles, test))
diff --git a/scripts/tests/test_protocol_vless.py b/scripts/tests/test_protocol_vless.py
new file mode 100644
index 0000000..bace8de
--- /dev/null
+++ b/scripts/tests/test_protocol_vless.py
@@ -0,0 +1,389 @@
+"""Offline evidence validation: no protocol listener or origin is launched."""
+
+from __future__ import annotations
+
+import copy
+import json
+import tempfile
+import tomllib
+import unittest
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import patch
+
+from vcore_scripts.builds import CORE_DIR, DEFAULT_FEATURES
+from vcore_scripts.protocol_evidence import RESOURCE_KINDS, load_manifest
+from vcore_scripts.protocol_vless_acceptance import (
+ FIELD_IDS,
+ NATIVE,
+ OBSERVATIONS,
+ REQUIRED_IDS,
+ definitions,
+ execute,
+ fields_report,
+ gate_result,
+ native_results,
+ required_command_names,
+)
+from vcore_scripts.protocol_vless_container import close_reference, run
+from vcore_scripts.protocol_vless_peers import configuration
+from vcore_scripts.protocol_vless_public import events_pass
+
+
+def pair(suite, name):
+ return [
+ dict(schema_version=1, suite=suite, assertion=name, status=status)
+ for status in ("BEGIN", "PASS")
+ ]
+
+
+class VlessEvidenceTest(unittest.TestCase):
+ def test_fingerprint_runner_rejects_unknown_profile_or_plaintext_before_io(self):
+ with tempfile.TemporaryDirectory() as directory:
+ output = Path(directory) / "must-not-exist"
+ for profile, cases in [
+ ("chrome133", ["VLESS-TCP-TLS-BASE"]),
+ ("chrome120", ["VLESS-TCP-BASE"]),
+ ]:
+ with self.assertRaises(ValueError):
+ run(output, cases, client_fingerprint=profile)
+ self.assertFalse(output.exists())
+
+ def test_official_ws_reference_preserves_vcore_default_and_explicit_ed_locations(
+ self,
+ ):
+ for specified in (None, "", "X-Synthetic-ED"):
+ options = {"max-early-data": 1, "v2ray-http-upgrade-fast-open": True}
+ if specified is not None:
+ options["early-data-header-name"] = specified
+ node = {"network": "ws", "ws-opts": options}
+ reference, scope = close_reference(
+ "upgrade-fast-tls", node, {}, Path("cert"), Path("key"), "pin"
+ )
+ self.assertEqual(scope, "same-mode")
+ self.assertEqual(
+ reference["ws-opts"]["early-data-header-name"],
+ "Sec-WebSocket-Protocol" if specified is None else specified,
+ )
+ self.assertEqual(
+ "early-data-header-name" in node["ws-opts"], specified is not None
+ )
+
+ def test_vision_flow_rejection_uses_plain_user_without_mutating_valid_peer(self):
+ for mode in ("vision-tls", "vision-reality"):
+ node, config = configuration(
+ mode, "server", "origin", Path("cert"), Path("key")
+ )
+ self.assertEqual(node["flow"], "xtls-rprx-vision")
+ valid, plain = config["listeners"]
+ self.assertEqual(valid["users"][0]["flow"], "xtls-rprx-vision")
+ self.assertEqual(plain["users"][0]["flow"], "")
+ self.assertEqual((valid["port"], plain["port"]), (23000, 23004))
+ self.assertEqual(valid.get("reality-config"), plain.get("reality-config"))
+ self.assertEqual(valid.get("certificate"), plain.get("certificate"))
+
+ def test_ws_reality_close_reference_is_explicitly_layered_not_same_mode(self):
+ node = {
+ "network": "ws",
+ "tls": True,
+ "port": 23000,
+ "reality-opts": {"public-key": "synthetic"},
+ }
+ config = {
+ "listeners": [{"port": 23000, "reality-config": {"dest": "synthetic"}}]
+ }
+ reference, scope = close_reference(
+ "ws-reality", node, config, Path("cert"), Path("key"), "pin"
+ )
+ self.assertEqual(scope, "ws-standard-tls-baseline")
+ self.assertIn("reality-opts", node)
+ self.assertNotIn("reality-opts", reference)
+ self.assertEqual(reference["port"], 23003)
+ self.assertIn("reality-config", config["listeners"][0])
+ self.assertNotIn("reality-config", config["listeners"][1])
+ case = next(
+ c for c in definitions() if c["case_id"] == "VLESS-WS-REALITY-CLOSE"
+ )
+ self.assertEqual(case["field_values"]["close_reference"], scope)
+ self.assertIn("not a same-combination", case["gap_source"]["reason"])
+
+ def test_jls_grpc_close_reference_labels_the_official_alpn_type_gap(self):
+ for profile in (None, "", "none", "chrome", "chrome120", "firefox", "safari"):
+ node = {
+ "network": "grpc",
+ "tls": True,
+ "jls-opts": {"username": "synthetic", "password": "synthetic"},
+ }
+ if profile is not None:
+ node["client-fingerprint"] = profile
+ original = copy.deepcopy(node)
+ reference, scope = close_reference(
+ "grpc-tls", node, {}, Path("cert"), Path("key"), "pin"
+ )
+ baseline = profile in (None, "", "none")
+ self.assertEqual(
+ scope, "jls-grpc-chrome-baseline" if baseline else "same-mode"
+ )
+ self.assertEqual(
+ reference["client-fingerprint"], "chrome" if baseline else profile
+ )
+ self.assertEqual(reference["jls-opts"], node["jls-opts"])
+ self.assertEqual(node, original)
+
+ for node in ({"network": "grpc"}, {"network": "tcp", "jls-opts": {}}):
+ reference, scope = close_reference(
+ "tcp-tls", node, {}, Path("cert"), Path("key"), "pin"
+ )
+ self.assertEqual(scope, "same-mode")
+ self.assertNotIn("client-fingerprint", reference)
+
+ def test_reality_close_reference_keeps_explicit_browser_profiles(self):
+ for profile in (None, "none", "chrome120", "firefox", "safari"):
+ node = {"network": "grpc"}
+ if profile is not None:
+ node["client-fingerprint"] = profile
+ reference, scope = close_reference(
+ "grpc-reality", node, {}, Path("cert"), Path("key"), "pin"
+ )
+ self.assertEqual(scope, "same-mode")
+ self.assertEqual(
+ reference["client-fingerprint"],
+ "chrome" if profile in (None, "none") else profile,
+ )
+
+ def test_safari_ech_close_reference_labels_the_official_client_gap(self):
+ for profile in ("safari", "safari16", "chrome", "firefox", "none"):
+ for enabled in (False, True):
+ node = {
+ "network": "grpc",
+ "tls": True,
+ "client-fingerprint": profile,
+ "ech-opts": {"enable": enabled, "config": "synthetic"},
+ }
+ original = copy.deepcopy(node)
+ reference, scope = close_reference(
+ "grpc-tls", node, {}, Path("cert"), Path("key"), "pin"
+ )
+ baseline = enabled and profile in ("safari", "safari16")
+ self.assertEqual(
+ scope, "ech-safari-chrome-baseline" if baseline else "same-mode"
+ )
+ self.assertEqual(
+ reference["client-fingerprint"], "chrome" if baseline else profile
+ )
+ self.assertEqual(reference["ech-opts"], node["ech-opts"])
+ self.assertEqual(node, original)
+
+ def test_independent_features_match_the_executed_command_set(self):
+ case = next(c for c in definitions() if c["case_id"] == "VLESS-FEATURES")
+ with (
+ tempfile.TemporaryDirectory() as root,
+ patch(
+ "vcore_scripts.protocol_harness._command",
+ return_value=SimpleNamespace(returncode=0, cleanup=True),
+ ) as command,
+ ):
+ execute([case], {"commands": []}, Path(root), {})
+ actual = {call.args[2] for call in command.call_args_list}
+ expected = {
+ name
+ for name in required_command_names()
+ if name.startswith("feature-") or name == "production-build"
+ }
+ self.assertEqual(actual, expected)
+
+ def test_required_manifest_cannot_drop_or_downgrade_behavior(self):
+ original = load_manifest()
+ index = next(i for i, case in enumerate(original) if case["stage"] == "VLESS")
+ for mutation in ("drop", "required", "observation", "row"):
+ cases = copy.deepcopy(original)
+ if mutation == "drop":
+ cases.pop(index)
+ elif mutation == "required":
+ cases[index]["required"] = False
+ elif mutation == "observation":
+ cases[index]["expected_observation"] = ["always-green"]
+ else:
+ cases[index]["row_ids"] = ["VL01"]
+ with tempfile.TemporaryDirectory() as root:
+ path = Path(root) / "cases.json"
+ path.write_text(
+ json.dumps(
+ dict(
+ schema_version=1,
+ kind="executable-case-manifest",
+ cases=cases,
+ )
+ )
+ )
+ with self.assertRaises(ValueError):
+ load_manifest(path)
+
+ def test_fields_require_complete_native_and_public_evidence(self):
+ cases = definitions()
+ self.assertEqual({c["case_id"] for c in cases}, REQUIRED_IDS)
+ self.assertEqual(
+ {c["case_id"] for c in cases if c["runner"] == "native-vless"}, set(NATIVE)
+ )
+ results = [dict(case_id=c["case_id"], status="PASS") for c in cases]
+ fields = fields_report(cases, results)["fields"]
+ self.assertEqual({f["row_id"] for f in fields}, FIELD_IDS)
+ self.assertTrue(all(f["status"] == "PASS" for f in fields))
+ for bad in (
+ results[:-1],
+ results[:-1] + [dict(case_id=results[-1]["case_id"], status="NOT RUN")],
+ ):
+ self.assertTrue(
+ all(
+ f["status"] == "NOT RUN"
+ for f in fields_report(cases, bad)["fields"]
+ )
+ )
+ features = tomllib.loads((CORE_DIR / "Cargo.toml").read_text())["features"]
+ for enabled in (
+ features["default"],
+ features["tun"],
+ DEFAULT_FEATURES.split(","),
+ ):
+ self.assertIn("outbound-vless", enabled)
+
+ def test_zero_partial_duplicate_failed_or_unjoined_rust_gate_is_not_pass(self):
+ cases = {c["case_id"]: c for c in definitions()}
+ for identifier, names in OBSERVATIONS.items():
+ case = cases[identifier]
+ events = [e for name in names for e in pair(identifier, name)]
+ commands = [dict(exit_code=0, cleanup=True)]
+ self.assertEqual(gate_result(case, commands, events)["status"], "PASS")
+ for bad in (
+ [],
+ events[:-1],
+ events + events[:1],
+ events[:-1] + [events[-1] | {"status": "FAIL"}],
+ ):
+ self.assertEqual(gate_result(case, commands, bad)["status"], "FAIL")
+ for record in (
+ dict(exit_code=124, cleanup=True),
+ dict(exit_code=0, cleanup=False),
+ ):
+ self.assertEqual(gate_result(case, [record], events)["status"], "FAIL")
+
+ def test_native_summary_cannot_hide_absent_events_changed_source_or_cleanup(self):
+ case = next(
+ c for c in definitions() if c["case_id"] == "VLESS-VISION-TLS-INNER-TLS"
+ )
+ test = case["peer_config"]["test"]
+ record = dict(
+ case_id=case["case_id"],
+ status="PASS",
+ exit_code=0,
+ command_cleanup=True,
+ cleanup=True,
+ peer_kind="M",
+ command=[
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ "vless_native",
+ test,
+ "--",
+ "--ignored",
+ "--exact",
+ "--nocapture",
+ ],
+ )
+ report = dict(cases=[record], source_unchanged=True, cleanup=True)
+ with tempfile.TemporaryDirectory() as root:
+ path = Path(root)
+ self.assertEqual(native_results([case], report, path)[0]["status"], "FAIL")
+ (path / (case["case_id"] + "-events.jsonl")).write_text(
+ "".join(json.dumps(e) + "\n" for e in pair("VLESS-WIRE", test))
+ )
+ self.assertEqual(native_results([case], report, path)[0]["status"], "PASS")
+ for key in ("cleanup", "source_unchanged"):
+ self.assertEqual(
+ native_results([case], report | {key: False}, path)[0]["status"],
+ "FAIL",
+ )
+ for change in (
+ dict(exit_code=124),
+ dict(command_cleanup=False),
+ dict(cleanup=False),
+ dict(command=[]),
+ dict(peer_kind="V2"),
+ ):
+ self.assertEqual(
+ native_results([case], report | {"cases": [record | change]}, path)[
+ 0
+ ]["status"],
+ "FAIL",
+ )
+ with self.assertRaises(ValueError):
+ native_results([case], report | {"cases": [record, record]}, path)
+
+ def test_public_base_requires_every_family_codec_and_body_option(self):
+ test = "public_base"
+ events = pair("VLESS-PUBLIC", test)
+ self.assertFalse(events_pass(events, test, "tcp"))
+ for name in ("tcp_10mib_both_directions", "udp_each_codec_and_family"):
+ events += [e for _ in range(3) for e in pair("VLESS-BASE", name)]
+ self.assertTrue(events_pass(events, test, "tcp"))
+ self.assertFalse(events_pass(events[:-2], test, "tcp"))
+ self.assertFalse(events_pass(events + events[-2:], test, "tcp"))
+ security = [
+ dict(event, suite=event["suite"].replace("VLESS-", "SECURITY-"))
+ for event in events
+ ]
+ self.assertTrue(events_pass(security, test, "tcp", stage="SECURITY"))
+ self.assertFalse(events_pass(security[:-2], test, "tcp", stage="SECURITY"))
+ self.assertFalse(events_pass(security, test, "tcp"))
+ vision = (
+ pair("VLESS-PUBLIC", test)
+ + [
+ e
+ for _ in range(3)
+ for e in pair("VLESS-BASE", "tcp_10mib_both_directions")
+ ]
+ + pair("VLESS-BASE", "udp_each_codec_and_family")
+ )
+ self.assertTrue(events_pass(vision, test, "vision-tls"))
+ self.assertFalse(events_pass(vision, test, "tcp"))
+
+ def test_owned_resources_need_twenty_idle_stop_and_quiet_cycles(self):
+ snapshot = dict(
+ counts=[
+ dict(kind=kind, current=0, peak=1) for kind in sorted(RESOURCE_KINDS)
+ ]
+ )
+ test = "runtime::owned_resources"
+ events = pair("VLESS-PUBLIC", test)
+ for _ in range(20):
+ cycle = pair("VLESS-OWNED", "stop_and_remain_quiet")
+ cycle[-1].update(
+ seconds=5,
+ resources=snapshot,
+ checkpoints=[
+ dict(phase=phase, resources=snapshot)
+ for phase in ("baseline", "after-stop", "quiet")
+ ],
+ )
+ events += cycle
+ self.assertTrue(events_pass(events, test, "tcp"))
+ for change in (
+ {"seconds": 4.9},
+ {"checkpoints": []},
+ {"resources": {}},
+ {"status": "FAIL"},
+ ):
+ self.assertFalse(
+ events_pass(events[:-1] + [events[-1] | change], test, "tcp")
+ )
+ self.assertFalse(events_pass(events[:-2], test, "tcp"))
+ busy = copy.deepcopy(events)
+ busy[-1]["resources"]["counts"][0]["current"] = 1
+ self.assertFalse(events_pass(busy, test, "tcp"))
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/scripts/tests/test_protocol_vmess.py b/scripts/tests/test_protocol_vmess.py
new file mode 100644
index 0000000..c6a0c88
--- /dev/null
+++ b/scripts/tests/test_protocol_vmess.py
@@ -0,0 +1,214 @@
+"""Offline evidence validation: no protocol listener or origin is launched."""
+
+from __future__ import annotations
+
+import copy
+import json
+import tempfile
+import tomllib
+import unittest
+from pathlib import Path
+
+from vcore_scripts.builds import CORE_DIR, DEFAULT_FEATURES
+from vcore_scripts.protocol_evidence import RESOURCE_KINDS, load_manifest
+from vcore_scripts.protocol_vmess_acceptance import (
+ FIELD_IDS,
+ NATIVE,
+ OBSERVATIONS,
+ REQUIRED_IDS,
+ definitions,
+ fields_report,
+ gate_result,
+ native_results,
+)
+from vcore_scripts.protocol_vmess_public import events_pass
+
+
+def pair(suite, name):
+ return [
+ dict(schema_version=1, suite=suite, assertion=name, status=status)
+ for status in ("BEGIN", "PASS")
+ ]
+
+
+class VmessEvidenceTest(unittest.TestCase):
+ def test_required_manifest_cannot_drop_or_downgrade_behavior(self):
+ original = load_manifest()
+ index = next(i for i, case in enumerate(original) if case["stage"] == "VMESS")
+ for mutation in ("drop", "required", "observation", "row"):
+ cases = copy.deepcopy(original)
+ if mutation == "drop":
+ cases.pop(index)
+ elif mutation == "required":
+ cases[index]["required"] = False
+ elif mutation == "observation":
+ cases[index]["expected_observation"] = ["always-green"]
+ else:
+ cases[index]["row_ids"] = ["VM01"]
+ with tempfile.TemporaryDirectory() as root:
+ path = Path(root) / "cases.json"
+ path.write_text(
+ json.dumps(
+ dict(
+ schema_version=1,
+ kind="executable-case-manifest",
+ cases=cases,
+ )
+ )
+ )
+ with self.assertRaises(ValueError):
+ load_manifest(path)
+
+ def test_fields_require_complete_native_and_public_evidence(self):
+ cases = definitions()
+ self.assertEqual({c["case_id"] for c in cases}, REQUIRED_IDS)
+ self.assertEqual(
+ {c["case_id"] for c in cases if c["runner"] == "native-vmess"}, set(NATIVE)
+ )
+ results = [dict(case_id=c["case_id"], status="PASS") for c in cases]
+ fields = fields_report(cases, results)["fields"]
+ self.assertEqual({f["row_id"] for f in fields}, FIELD_IDS)
+ self.assertTrue(all(f["status"] == "PASS" for f in fields))
+ for bad in (
+ results[:-1],
+ results[:-1] + [dict(case_id=results[-1]["case_id"], status="NOT RUN")],
+ ):
+ self.assertTrue(
+ all(
+ f["status"] == "NOT RUN"
+ for f in fields_report(cases, bad)["fields"]
+ )
+ )
+ features = tomllib.loads((CORE_DIR / "Cargo.toml").read_text())["features"]
+ for enabled in (
+ features["default"],
+ features["tun"],
+ DEFAULT_FEATURES.split(","),
+ ):
+ self.assertIn("outbound-vmess", enabled)
+
+ def test_zero_partial_duplicate_failed_or_unjoined_rust_gate_is_not_pass(self):
+ cases = {c["case_id"]: c for c in definitions()}
+ for identifier, names in OBSERVATIONS.items():
+ case = cases[identifier]
+ events = [e for name in names for e in pair(identifier, name)]
+ commands = [dict(exit_code=0, cleanup=True)]
+ self.assertEqual(gate_result(case, commands, events)["status"], "PASS")
+ for bad in (
+ [],
+ events[:-1],
+ events + events[:1],
+ events[:-1] + [events[-1] | {"status": "FAIL"}],
+ ):
+ self.assertEqual(gate_result(case, commands, bad)["status"], "FAIL")
+ for record in (
+ dict(exit_code=124, cleanup=True),
+ dict(exit_code=0, cleanup=False),
+ ):
+ self.assertEqual(gate_result(case, [record], events)["status"], "FAIL")
+
+ def test_native_summary_cannot_hide_absent_events_changed_source_or_cleanup(self):
+ case = next(c for c in definitions() if c["case_id"] == "VMESS-M-IDENTITY")
+ test = case["peer_config"]["test"]
+ record = dict(
+ case_id=case["case_id"],
+ status="PASS",
+ exit_code=0,
+ command_cleanup=True,
+ cleanup=True,
+ peer_kind="M",
+ command=[
+ "cargo",
+ "test",
+ "--locked",
+ "--all-features",
+ "--test",
+ "vmess_native",
+ test,
+ "--",
+ "--ignored",
+ "--exact",
+ "--nocapture",
+ ],
+ )
+ report = dict(cases=[record], source_unchanged=True, cleanup=True)
+ with tempfile.TemporaryDirectory() as root:
+ path = Path(root)
+ self.assertEqual(native_results([case], report, path)[0]["status"], "FAIL")
+ (path / (case["case_id"] + "-events.jsonl")).write_text(
+ "".join(json.dumps(e) + "\n" for e in pair("VMESS-WIRE", test))
+ )
+ self.assertEqual(native_results([case], report, path)[0]["status"], "PASS")
+ for key in ("cleanup", "source_unchanged"):
+ self.assertEqual(
+ native_results([case], report | {key: False}, path)[0]["status"],
+ "FAIL",
+ )
+ for change in (
+ dict(exit_code=124),
+ dict(command_cleanup=False),
+ dict(cleanup=False),
+ dict(command=[]),
+ dict(peer_kind="V2"),
+ ):
+ self.assertEqual(
+ native_results([case], report | {"cases": [record | change]}, path)[
+ 0
+ ]["status"],
+ "FAIL",
+ )
+ with self.assertRaises(ValueError):
+ native_results([case], report | {"cases": [record, record]}, path)
+
+ def test_public_base_requires_every_family_codec_and_body_option(self):
+ test = "public_base"
+ events = pair("VMESS-PUBLIC", test)
+ self.assertFalse(events_pass(events, test))
+ for name in ("tcp_10mib_both_directions", "udp_each_codec_and_family"):
+ events += [e for _ in range(3) for e in pair("VMESS-BASE", name)]
+ self.assertTrue(events_pass(events, test))
+ self.assertFalse(events_pass(events[:-2], test))
+ self.assertFalse(events_pass(events + events[-2:], test))
+ body = pair("VMESS-PUBLIC", "public_body_options") + [
+ e
+ for _ in range(14)
+ for e in pair("VMESS-BODY", "config_controls_aead_body")
+ ]
+ self.assertTrue(events_pass(body, "public_body_options"))
+ self.assertFalse(events_pass(body[:-2], "public_body_options"))
+
+ def test_owned_resources_need_twenty_idle_stop_and_quiet_cycles(self):
+ snapshot = dict(
+ counts=[
+ dict(kind=kind, current=0, peak=1) for kind in sorted(RESOURCE_KINDS)
+ ]
+ )
+ test = "runtime::owned_resources"
+ events = pair("VMESS-PUBLIC", test)
+ for _ in range(20):
+ cycle = pair("VMESS-OWNED", "stop_and_remain_quiet")
+ cycle[-1].update(
+ seconds=5,
+ resources=snapshot,
+ checkpoints=[
+ dict(phase=phase, resources=snapshot)
+ for phase in ("baseline", "after-stop", "quiet")
+ ],
+ )
+ events += cycle
+ self.assertTrue(events_pass(events, test))
+ for change in (
+ {"seconds": 4.9},
+ {"checkpoints": []},
+ {"resources": {}},
+ {"status": "FAIL"},
+ ):
+ self.assertFalse(events_pass(events[:-1] + [events[-1] | change], test))
+ self.assertFalse(events_pass(events[:-2], test))
+ busy = copy.deepcopy(events)
+ busy[-1]["resources"]["counts"][0]["current"] = 1
+ self.assertFalse(events_pass(busy, test))
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/scripts/tests/test_protocol_vmess_udp_ab.py b/scripts/tests/test_protocol_vmess_udp_ab.py
new file mode 100644
index 0000000..acb1a12
--- /dev/null
+++ b/scripts/tests/test_protocol_vmess_udp_ab.py
@@ -0,0 +1,30 @@
+"""Small offline checks for diagnostic evidence extraction, not interop."""
+
+import tempfile
+import unittest
+from pathlib import Path
+
+from vcore_scripts.protocol_vmess_udp_ab import options, warning_summary
+
+
+class UdpDiagnosticTests(unittest.TestCase):
+ def test_matched_body_options(self):
+ matrix = options(["raw", "xudp", "packetaddr"])
+ self.assertEqual(len(matrix), 39)
+ self.assertEqual(sum(item["cipher"] == "none" for item in matrix), 3)
+
+ def test_loopback_ports_include_domain_and_exclude_timestamp(self):
+ with tempfile.TemporaryDirectory() as root:
+ log = Path(root) / "peer.log"
+ log.write_text(
+ 'time="2026-09-23T10:27:13+08:00" level=warning '
+ 'msg="[UDP] 127.0.0.1:51243 --> vcore-fixture.test:63254 '
+ 'error: reject loopback connection to: vcore-fixture.test:63254"\n'
+ 'time="2026-09-23T10:27:14+08:00" level=warning '
+ 'msg="[UDP] 127.0.0.1:51386 --> [::1]:64969 '
+ 'error: reject loopback connection to: [::1]:64969"\n'
+ )
+ self.assertEqual(
+ warning_summary(log)["loopback_rejections"],
+ [{"ports": [51243, 63254, 63254]}, {"ports": [51386, 64969, 64969]}],
+ )
diff --git a/scripts/tests/test_protocol_xhttp.py b/scripts/tests/test_protocol_xhttp.py
new file mode 100644
index 0000000..473e805
--- /dev/null
+++ b/scripts/tests/test_protocol_xhttp.py
@@ -0,0 +1,105 @@
+"""Fail-closed XHTTP coverage and fixture checks; no host listeners."""
+
+import copy
+import unittest
+
+from vcore_scripts.protocol_xhttp_acceptance import (
+ FIELD_IDS,
+ NATIVE,
+ OBSERVATIONS,
+ definitions,
+ gate_result,
+ native_results,
+)
+from vcore_scripts.protocol_xhttp_fields import events_pass, public_events_pass
+
+
+def pair(suite, assertion):
+ return [
+ dict(schema_version=1, suite=suite, assertion=assertion, status=s)
+ for s in ("BEGIN", "PASS")
+ ]
+
+
+class XhttpAcceptanceTest(unittest.TestCase):
+ def test_frozen_catalog_has_all_rows_modes_and_mux_wires(self):
+ cases = definitions()
+ self.assertEqual(len(FIELD_IDS), 57)
+ self.assertEqual(len(cases), len({c["case_id"] for c in cases}))
+ self.assertEqual(FIELD_IDS, set().union(*(set(c["row_ids"]) for c in cases)))
+ for version in ("h1", "h2", "h1c", "h2c", "h1r", "h2r", "h3"):
+ for mode in ("stream-one", "stream-up", "packet-up"):
+ self.assertTrue(
+ any(
+ v == f"{version}-{mode}-headers" and test == "public_base"
+ for v, test in NATIVE.values()
+ )
+ )
+ for protocol in ("h2mux", "smux", "yamux"):
+ self.assertTrue(
+ any(
+ v.startswith(f"{version}-mux-{protocol}-")
+ and test == "public_base"
+ for v, test in NATIVE.values()
+ )
+ )
+ for version in ("h1r", "h2r"):
+ for field in ("public-key", "short-id"):
+ self.assertIn(
+ (
+ f"{version}-reject-download-{field}",
+ "security::native_xhttp_security",
+ ),
+ NATIVE.values(),
+ )
+
+ def test_unknown_duplicate_wrong_suite_and_partial_events_fail(self):
+ observed = pair("XHTTP-XHTTP", "native_xhttp_request_fields")
+ self.assertTrue(events_pass(observed, "native_xhttp_request_fields"))
+ for bad in (
+ [],
+ observed[:1],
+ observed * 2,
+ observed + pair("extra", "unknown"),
+ ):
+ self.assertFalse(events_pass(bad, "native_xhttp_request_fields"))
+ public = pair("XHTTP-PUBLIC", "runtime::public_graph")
+ self.assertTrue(public_events_pass(public, "runtime::public_graph"))
+ self.assertFalse(
+ public_events_pass(
+ public + pair("XHTTP-BASE", "unknown"), "runtime::public_graph"
+ )
+ )
+ bad = copy.deepcopy(public)
+ bad[1]["schema_version"] = 2
+ self.assertFalse(public_events_pass(bad, "runtime::public_graph"))
+
+ def test_unit_gate_requires_every_frozen_assertion_and_successful_command(self):
+ case = next(c for c in definitions() if c["case_id"] == "XHTTP-CFG")
+ events = sum(
+ (pair("XHTTP-UNIT", name) for name in OBSERVATIONS["XHTTP-CFG"]), []
+ )
+ records = [dict(exit_code=0, cleanup=True)]
+ self.assertEqual(gate_result(case, records, events)["status"], "PASS")
+ for bad in ([], events[:-1], events + events[:2]):
+ self.assertEqual(gate_result(case, records, bad)["status"], "FAIL")
+ self.assertEqual(
+ gate_result(case, [dict(exit_code=1, cleanup=True)], events)["status"],
+ "FAIL",
+ )
+
+ def test_native_missing_and_duplicate_records_are_not_success(self):
+ case = next(c for c in definitions() if c["case_id"] in NATIVE)
+ for records in ([], [dict(case_id=case["case_id"])] * 2):
+ with self.assertRaises(ValueError):
+ native_results([case], dict(cases=records), None)
+ self.assertEqual(
+ native_results([case], dict(cases=[]), None, allow_partial=True), []
+ )
+ for records in ([dict(case_id="unknown")], [dict(case_id=case["case_id"])] * 2):
+ with self.assertRaises(ValueError):
+ native_results([case], dict(cases=records), None, allow_partial=True)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/scripts/tests/test_scripts.py b/scripts/tests/test_scripts.py
index d959761..8c99ef4 100644
--- a/scripts/tests/test_scripts.py
+++ b/scripts/tests/test_scripts.py
@@ -1,6 +1,7 @@
from __future__ import annotations
import copy
+import hashlib
import json
import subprocess
import sys
@@ -11,14 +12,14 @@ import xml.etree.ElementTree as ET
from contextlib import ExitStack
from pathlib import Path
from types import SimpleNamespace
-from unittest.mock import MagicMock, patch
+from unittest.mock import MagicMock, call, patch
from vcore_scripts import builds, cli, mihomo
from vcore_scripts.builds import EXPECTED_IDENTITY, _android_target, _require_identity
from vcore_scripts.checks import (
+ BORING_GIT_SOURCE,
+ BORING_REVISION,
CRATES_IO_SOURCES,
- RUSTLS_GIT_SOURCE_PREFIX,
- SHADOWSOCKS_GIT_SOURCE,
_shadowsocks_aws_lc_errors,
_tls_dependency_errors,
)
@@ -51,51 +52,30 @@ class ScriptTest(unittest.TestCase):
)
self.assertNotIn("interop-test", features)
- def test_mihomo_check_dispatches_and_missing_peer_is_not_success(self):
- with patch("vcore_scripts.cli.run_mihomo_interop") as run:
+ def test_download_cli_dispatches_host_and_container_target(self):
+ with patch("vcore_scripts.cli.download_mihomo") as fetch:
+ self.assertEqual(cli.main(["download", "mihomo"]), 0)
self.assertEqual(
- cli.main(["check", "mihomo-interop", "--binary", "fixture-mihomo"]), 0
+ cli.main(["download", "mihomo", "--target", "linux-arm64"]), 0
)
- run.assert_called_once_with(Path("fixture-mihomo"))
- with (
- tempfile.TemporaryDirectory() as directory,
- self.assertRaisesRegex(RuntimeError, "NOT RUN"),
- ):
- mihomo.run_mihomo_interop(Path(directory) / "missing")
+ self.assertEqual(fetch.call_args_list, [call(None), call("linux-arm64")])
- def test_extended_mihomo_dispatch_and_soak_bounds(self):
- with patch("vcore_scripts.cli.run_mihomo_interop") as run:
- self.assertEqual(
- cli.main(
- ["check", "mihomo-interop", "--extended", "--soak-seconds", "90"]
- ),
- 0,
- )
- run.assert_called_once_with(
- None, extended=True, soak_seconds=90, container_binary=None
- )
- for extended, seconds in [(False, 1), (True, -1), (True, 7201)]:
- with (
- self.subTest(extended=extended, seconds=seconds),
- self.assertRaises(ValueError),
- ):
- mihomo.run_mihomo_interop(extended=extended, soak_seconds=seconds)
-
- def test_container_cli_dispatch(self):
- with patch("vcore_scripts.cli.run_mihomo_interop") as run:
+ def test_legacy_demo_requires_explicit_config_and_source(self):
+ with patch("vcore_scripts.cli.run_demo") as run:
self.assertEqual(
cli.main(
[
- "check",
- "mihomo-interop",
- "--container-binary",
- "linux-mihomo",
+ "demo",
+ "windows-tun2socks",
+ "fixture.json",
+ "--xray-source",
+ "fixture-xray",
]
),
0,
)
run.assert_called_once_with(
- None, extended=False, soak_seconds=0, container_binary=Path("linux-mihomo")
+ Path("fixture.json"), xray_source=Path("fixture-xray")
)
def test_container_bridge_ipv6_does_not_select_lan_or_utun(self):
@@ -304,6 +284,57 @@ except RuntimeError as error:
with self.assertRaisesRegex(RuntimeError, "unsupported Android Rust target"):
_android_target("mips-linux-android", "24")
+ def test_android_build_packages_the_matching_ndk_cpp_runtime(self):
+ with tempfile.TemporaryDirectory() as directory:
+ root = Path(directory)
+ toolchain = root / "ndk/toolchain"
+ (toolchain / "bin").mkdir(parents=True)
+ (toolchain / "bin/llvm-ar").touch()
+ targets = ("aarch64-linux-android", "x86_64-linux-android")
+ for target in targets:
+ abi, clang, _ = _android_target(target, "24")
+ (toolchain / "bin" / clang).touch()
+ (toolchain / "bin" / (clang + "++")).touch()
+ runtime = toolchain / "sysroot/usr/lib" / target / "libc++_shared.so"
+ runtime.parent.mkdir(parents=True)
+ runtime.write_bytes(abi.encode())
+ artifact = root / "target" / target / "release/libvcore.so"
+ artifact.parent.mkdir(parents=True)
+ artifact.write_bytes(EXPECTED_IDENTITY)
+ with (
+ patch.dict(
+ builds.os.environ,
+ {"ANDROID_NDK_HOME": str(root / "ndk")},
+ clear=True,
+ ),
+ patch.object(builds, "CORE_DIR", root),
+ patch.object(builds, "_android_toolchain", return_value=toolchain),
+ patch.object(builds, "_require_targets"),
+ patch.object(builds, "_cargo_build") as cargo,
+ ):
+ builds.build_android()
+ self.assertEqual(cargo.call_count, 2)
+ for invocation, target in zip(cargo.call_args_list, targets, strict=True):
+ abi, clang, _ = _android_target(target, "24")
+ env = invocation.args[3]
+ self.assertEqual(env["VCORE_CMAKE_ANDROID_ABI"], abi)
+ self.assertEqual(env["VCORE_CMAKE_ANDROID_API"], "24")
+ self.assertEqual(
+ env[f"CMAKE_TOOLCHAIN_FILE_{target.replace('-', '_')}"],
+ str(root / "scripts/cmake/android.toolchain.cmake"),
+ )
+ self.assertEqual(
+ env[f"CXX_{target.replace('-', '_')}"],
+ str(toolchain / "bin" / (clang + "++")),
+ )
+ output = root / "dist/android" / abi
+ self.assertEqual(
+ (output / "libvcore.so").read_bytes(), EXPECTED_IDENTITY
+ )
+ self.assertEqual(
+ (output / "libc++_shared.so").read_bytes(), abi.encode()
+ )
+
def test_artifact_identity_check_reads_binary_directly(self):
with tempfile.TemporaryDirectory() as directory:
artifact = Path(directory) / "libvcore.a"
@@ -355,9 +386,7 @@ except RuntimeError as error:
root / "dist/windows/arm64/vcore-windows-artifacts.json"
).read_text()
)
- expected_digest = (
- "bfb78d72918e79702c425f161b4889064a68981ce9f5e69da78166f4ad56e3e8"
- )
+ expected_digest = hashlib.sha256(_windows_pe(0xAA64)).hexdigest()
self.assertEqual(
manifest,
{
@@ -397,13 +426,13 @@ except RuntimeError as error:
{
"id": "rustls-id",
"name": "rustls",
- "version": "0.23.43",
- "source": RUSTLS_GIT_SOURCE_PREFIX + "a" * 40,
+ "version": "0.23.45",
+ "source": registry,
},
{
"id": "tokio-rustls-id",
"name": "tokio-rustls",
- "version": "0.26.4",
+ "version": "0.26.5",
"source": registry,
},
{
@@ -412,18 +441,138 @@ except RuntimeError as error:
"version": "0.17.14",
"source": registry,
},
+ *[
+ dict(id=name, name=name, version="5.2.0", source=BORING_GIT_SOURCE)
+ for name in ("boring", "boring-sys", "tokio-boring")
+ ],
+ dict(id="hpke", name="hpke", version="0.14.1", source=registry),
],
"resolve": {
"nodes": [
{
"id": "rustls-id",
- "features": ["reality", "ring", "std", "tls12"],
- }
+ "features": ["ring", "std", "tls12"],
+ "deps": [],
+ },
+ {
+ "id": "boring",
+ "features": [
+ "reality",
+ "client-fingerprint",
+ "shadow-tls-v3",
+ "jls",
+ ],
+ "deps": [{"pkg": "boring-sys"}],
+ },
+ {
+ "id": "boring-sys",
+ "features": ["reality", "shadow-tls-v3", "jls"],
+ },
+ {
+ "id": "tokio-boring",
+ "features": [],
+ "deps": [{"pkg": "boring"}, {"pkg": "boring-sys"}],
+ },
+ {
+ "id": "hpke",
+ "features": ["alloc", "aes", "chacha", "x25519", "hkdfsha2"],
+ },
]
},
}
self.assertEqual(_tls_dependency_errors(metadata), [])
+ for invalid_source in (None, BORING_GIT_SOURCE):
+ invalid = copy.deepcopy(metadata)
+ invalid["packages"][-1]["source"] = invalid_source
+ self.assertTrue(_tls_dependency_errors(invalid))
+ for feature in ("alloc", "aes", "chacha", "x25519"):
+ invalid = copy.deepcopy(metadata)
+ invalid["resolve"]["nodes"][-1]["features"].remove(feature)
+ self.assertTrue(_tls_dependency_errors(invalid))
+
+ for index, old_version in [(0, "0.23.43"), (1, "0.26.4"), (3, "5.1.0")]:
+ with self.subTest(outdated_version=old_version):
+ outdated = copy.deepcopy(metadata)
+ outdated["packages"][index]["version"] = old_version
+ self.assertTrue(_tls_dependency_errors(outdated))
+
+ for source in [
+ None,
+ registry,
+ BORING_GIT_SOURCE.rsplit("#", 1)[0] + "#" + "f" * 40,
+ BORING_GIT_SOURCE.replace("?branch=release", "?branch=main"),
+ BORING_GIT_SOURCE.replace("?branch=release", f"?rev={BORING_REVISION}"),
+ BORING_GIT_SOURCE.replace("OneXray/boring", "example/boring"),
+ ]:
+ for index in (3, 4, 5):
+ with self.subTest(boring_source=source, package=index):
+ invalid = copy.deepcopy(metadata)
+ invalid["packages"][index]["source"] = source
+ self.assertTrue(_tls_dependency_errors(invalid))
+
+ for required in ["reality", "client-fingerprint", "shadow-tls-v3", "jls"]:
+ with self.subTest(boring_feature=required):
+ invalid = copy.deepcopy(metadata)
+ invalid["resolve"]["nodes"][1]["features"].remove(required)
+ self.assertTrue(_tls_dependency_errors(invalid))
+
+ for missing in ["edge", "node", "package"]:
+ with self.subTest(boring_missing=missing):
+ invalid = copy.deepcopy(metadata)
+ if missing == "edge":
+ invalid["resolve"]["nodes"][1]["deps"] = []
+ elif missing == "node":
+ invalid["resolve"]["nodes"].pop()
+ else:
+ invalid["packages"].pop()
+ self.assertTrue(_tls_dependency_errors(invalid))
+
+ for forbidden in ["reality", "aws_lc_rs", "fips"]:
+ invalid = copy.deepcopy(metadata)
+ invalid["resolve"]["nodes"][0]["features"].append(forbidden)
+ self.assertTrue(_tls_dependency_errors(invalid))
+
+ for forbidden in ("fips", "restls"):
+ for index in (1, 2, 3):
+ with self.subTest(native_feature=forbidden, node=index):
+ invalid = copy.deepcopy(metadata)
+ invalid["resolve"]["nodes"][index]["features"].append(forbidden)
+ self.assertTrue(_tls_dependency_errors(invalid))
+
+ for source in CRATES_IO_SOURCES:
+ with self.subTest(rustls_registry=source):
+ official = copy.deepcopy(metadata)
+ official["packages"][0]["source"] = source
+ self.assertEqual(_tls_dependency_errors(official), [])
+
+ for source in (
+ None,
+ "git+https://example.invalid/rustls?branch=custom#" + "a" * 40,
+ "git+https://github.com/rustls/rustls#" + "a" * 40,
+ "registry+https://example.invalid/index",
+ ):
+ with self.subTest(rustls_source=source):
+ invalid = copy.deepcopy(metadata)
+ invalid["packages"][0]["source"] = source
+ self.assertTrue(
+ any(
+ "rustls must come from crates.io" in error
+ for error in _tls_dependency_errors(invalid)
+ )
+ )
+
+ duplicate = copy.deepcopy(metadata)
+ duplicate["packages"].append(
+ dict(
+ id="second-rustls",
+ name="rustls",
+ version="0.23.45",
+ source="git+https://github.com/rustls/rustls#" + "a" * 40,
+ )
+ )
+ self.assertTrue(_tls_dependency_errors(duplicate))
+
metadata["packages"].append(
{
"id": "aws-id",
@@ -442,7 +591,7 @@ except RuntimeError as error:
metadata["packages"][0]["source"] = None
self.assertTrue(
any(
- "vcore/reality-0.23 GitHub branch" in error
+ "rustls must come from crates.io" in error
for error in _tls_dependency_errors(metadata)
)
)
@@ -456,7 +605,7 @@ except RuntimeError as error:
for name, version, source in zip(
names,
["1.25.0", "0.8.0", "1.18.1", "0.45.0"],
- [SHADOWSOCKS_GIT_SOURCE, registry, registry, registry],
+ [registry] * 4,
strict=True,
)
],
@@ -478,6 +627,21 @@ except RuntimeError as error:
},
}
self.assertEqual(_shadowsocks_aws_lc_errors(metadata), [])
+ for source in CRATES_IO_SOURCES:
+ with self.subTest(shadowsocks_registry=source):
+ official = copy.deepcopy(metadata)
+ official["packages"][0]["source"] = source
+ self.assertEqual(_shadowsocks_aws_lc_errors(official), [])
+ for source in (
+ "git+https://github.com/shadowsocks/shadowsocks-rust.git?rev="
+ "ab388c7466d21f979430e33cc9ef10e22fb05955#"
+ "ab388c7466d21f979430e33cc9ef10e22fb05955",
+ "registry+https://example.invalid/index",
+ ):
+ with self.subTest(shadowsocks_source=source):
+ invalid = copy.deepcopy(metadata)
+ invalid["packages"][0]["source"] = source
+ self.assertTrue(_shadowsocks_aws_lc_errors(invalid))
for index, feature in [(0, "aead-cipher-2022-extra"), (1, "v2-extra")]:
invalid = copy.deepcopy(metadata)
invalid["resolve"]["nodes"][index]["features"].append(feature)
diff --git a/scripts/tests/test_selected_fingerprint_gates.py b/scripts/tests/test_selected_fingerprint_gates.py
new file mode 100644
index 0000000..ab7c777
--- /dev/null
+++ b/scripts/tests/test_selected_fingerprint_gates.py
@@ -0,0 +1,119 @@
+"""Offline guardrails for selected-profile coverage and explicit differences."""
+
+import copy
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+from vcore_scripts.builds import CORE_DIR
+from vcore_scripts.protocol_fingerprint import CASES
+from vcore_scripts.protocol_fingerprint_reference import _reference_shape
+from vcore_scripts.protocol_fingerprint_shape import (
+ check_captures,
+ check_warm_captures,
+ expected_shape,
+)
+from vcore_scripts.protocol_inputs import same_source
+from vcore_scripts.protocol_xhttp_fields import (
+ run,
+ selected_gateway_config,
+ selected_profile_variants,
+)
+from vcore_scripts.tls_client_hello import validate_capture
+
+
+class SelectedFingerprintGatesTest(unittest.TestCase):
+ def test_staging_metadata_is_not_a_source_change(self):
+ source = dict(
+ parent_commit="parent",
+ source_tree_sha256="tree",
+ lock_sha256="lock",
+ dirty_patch_sha256="unstaged",
+ )
+ self.assertTrue(same_source(source, dict(source, dirty_patch_sha256="staged")))
+ for field in ("parent_commit", "source_tree_sha256", "lock_sha256"):
+ self.assertFalse(same_source(source, dict(source, **{field: "changed"})))
+
+ def test_partial_wire_and_warm_matrices_never_pass(self):
+ for check in (check_captures, check_warm_captures):
+ with self.assertRaises(ValueError):
+ check([])
+
+ def test_reality_does_not_inherit_standard_tls13_template_pruning(self):
+ samples = json.loads(
+ (CORE_DIR / "tests/fingerprints/mihomo-selected-v1.json").read_text()
+ )["samples"]
+ sample = next(
+ s
+ for s in samples
+ if s["profile"] == "firefox" and s["context"] == "reality"
+ )
+ shape = expected_shape(sample, "reality")
+ self.assertEqual(shape["ciphers"], validate_capture(sample)["ciphers"])
+ self.assertEqual(len(shape["ciphers"]), 17)
+ hello = copy.deepcopy(validate_capture(sample))
+ psk = dict(type=41, bytes=50, identities=[7], binders=[32])
+ hello["extensions"].append(psk)
+ hello["bytes"] += 54
+ case = dict(template="Firefox120", sni="fingerprint.test", context="reality")
+ with self.assertRaises(ValueError):
+ _reference_shape(hello, case)
+ self.assertEqual(
+ _reference_shape(hello, case, allow_psk=True)["extensions"][-1], psk
+ )
+ hello["extensions"].insert(0, hello["extensions"].pop())
+ with self.assertRaises(ValueError):
+ _reference_shape(hello, case, allow_psk=True)
+
+ def test_transport_catalog_includes_existing_native_and_upgrade_paths(self):
+ for name in (
+ "VLESS-UPGRADE-TLS-BASE",
+ "VLESS-UPGRADE-FAST-TLS-BASE",
+ "VLESS-H2-TLS-BASE",
+ "VLESS-HTTP-TLS-BASE",
+ "VLESS-WS-ED-2048-TLS-BASE",
+ "FINGERPRINT-VMESS-H2-TLS",
+ "FINGERPRINT-VMESS-HTTP-TLS",
+ ):
+ self.assertIn(name, CASES)
+ self.assertEqual(len(CASES), len(set(CASES)))
+
+ def test_download_crossings_are_explicit_and_h3_requires_clear(self):
+ cases = selected_profile_variants("chrome")
+
+ def get(suffix):
+ return cases[f"h2-selected-download-{suffix}"][0]["download-settings"]
+
+ self.assertNotIn("client-fingerprint", get("inherit"))
+ self.assertEqual(get("different")["client-fingerprint"], "firefox")
+ self.assertEqual(get("clear")["client-fingerprint"], "none")
+ h3 = cases["h3-selected-download-clear"][0]
+ self.assertEqual(h3["_main_alpn"], "h2")
+ self.assertEqual(h3["download-settings"]["client-fingerprint"], "none")
+ parent = CORE_DIR / "target/interop/runs"
+ parent.mkdir(parents=True, exist_ok=True)
+ with tempfile.TemporaryDirectory(dir=parent) as directory:
+ output = Path(directory) / "not-created"
+ for profile, selection in [
+ ("chrome133", ["h2-auto"]),
+ ("chrome", ["h3-auto"]),
+ ("chrome", ["h2c-auto"]),
+ ("none", ["h2c-auto"]),
+ ]:
+ with self.assertRaises(ValueError):
+ run(output, selection, client_fingerprint=profile)
+ self.assertFalse(output.exists())
+
+ def test_split_h2_h3_uses_a_gateway_with_one_native_handler(self):
+ fixture = selected_gateway_config("192.0.2.1")["apps"]["http"]["servers"][
+ "fixture"
+ ]
+ self.assertEqual(fixture["protocols"], ["h2", "h3"])
+ handler = fixture["routes"][0]["handle"][0]
+ self.assertEqual(handler["upstreams"], [{"dial": "192.0.2.1:23000"}])
+ self.assertEqual(handler["transport"]["versions"], ["h2c"])
+ self.assertEqual(
+ fixture["tls_connection_policies"][0]["client_authentication"]["mode"],
+ "require_and_verify",
+ )
diff --git a/scripts/tests/test_tls_client_hello.py b/scripts/tests/test_tls_client_hello.py
new file mode 100644
index 0000000..5fc8c88
--- /dev/null
+++ b/scripts/tests/test_tls_client_hello.py
@@ -0,0 +1,146 @@
+"""RFC-shaped, in-memory ClientHello observations; no sockets or peers."""
+
+import copy
+import json
+import unittest
+
+from vcore_scripts.builds import CORE_DIR
+from vcore_scripts.tls_client_hello import (
+ compare_client_hellos,
+ parse_client_hello,
+ validate_capture,
+)
+
+# RFC 8446 vectors with synthetic random bytes, in their encoded order.
+HELLO = bytes.fromhex(
+ "010000590303"
+ + "00" * 32
+ + "0000041301c02f0100002c"
+ + "000a00060004001d0017"
+ + "000d0006000404030804"
+ + "002b00050403040303"
+ + "0010000b000908687474702f312e31"
+)
+
+
+def extensions_hello(extensions):
+ body = HELLO[4:47] + len(extensions).to_bytes(2, "big") + extensions
+ return b"\x01" + len(body).to_bytes(3, "big") + body
+
+
+class ClientHelloTest(unittest.TestCase):
+ def test_raw_official_fixture_detects_tampered_parsed_evidence(self):
+ samples = json.loads(
+ (CORE_DIR / "tests/fingerprints/mihomo-selected-v1.json").read_text()
+ )["samples"]
+ for sample in samples:
+ self.assertEqual(validate_capture(sample), sample["parsed"])
+ corrupted = copy.deepcopy(samples[0])
+ corrupted["parsed"]["ciphers"].reverse()
+ with self.assertRaises(ValueError):
+ validate_capture(corrupted)
+
+ def test_preserves_ordered_tls_vectors(self):
+ hello = parse_client_hello(HELLO)
+ self.assertEqual(hello["ciphers"], [0x1301, 0xC02F])
+ self.assertEqual(
+ hello["extensions"],
+ [
+ {"type": 10, "bytes": 6, "values": [29, 23]},
+ {"type": 13, "bytes": 6, "values": [0x0403, 0x0804]},
+ {"type": 43, "bytes": 5, "values": [0x0304, 0x0303]},
+ {"type": 16, "bytes": 11, "protocols": ["http/1.1"]},
+ ],
+ )
+
+ def test_retains_key_share_and_ech_layout_without_random_key_bytes(self):
+ data = extensions_hello(
+ bytes.fromhex("0033002b00290a0a000100001d0020" + "11" * 32)
+ + bytes.fromhex("fe0d000f0000010001120004abababab0001ac")
+ )
+
+ hello = parse_client_hello(data)
+ self.assertEqual(
+ hello["extensions"],
+ [
+ {
+ "type": 51,
+ "bytes": 43,
+ "shares": [
+ {"group": 0x0A0A, "bytes": 1, "grease_data": "00"},
+ {"group": 29, "bytes": 32},
+ ],
+ },
+ {
+ "type": 65037,
+ "bytes": 15,
+ "hello_type": 0,
+ "kdf": 1,
+ "aead": 1,
+ "enc_bytes": 4,
+ "payload_bytes": 1,
+ },
+ ],
+ )
+
+ def test_comparison_ignores_random_bytes_but_not_order_or_lengths(self):
+ random_changed = bytearray(HELLO)
+ random_changed[6:38] = b"\x12" * 32
+ self.assertEqual(compare_client_hellos(HELLO, bytes(random_changed)), [])
+ cipher_changed = bytearray(HELLO)
+ cipher_changed[41:45] = bytes.fromhex("c02f1301")
+ self.assertIn("ciphers", compare_client_hellos(HELLO, bytes(cipher_changed)))
+ reordered = extensions_hello(HELLO[59:69] + HELLO[49:59] + HELLO[69:])
+ self.assertIn("extensions", compare_client_hellos(HELLO, reordered))
+ self.assertEqual(
+ compare_client_hellos(HELLO, reordered, shuffle_extensions=True), []
+ )
+
+ def test_reports_ticket_binder_sni_and_compression_structure(self):
+ hello = parse_client_hello(
+ extensions_hello(
+ bytes.fromhex("00000009000700000474657374")
+ + bytes.fromhex("001b00050400010002")
+ + bytes.fromhex("00290030000b0005616263646500000000002120" + "55" * 32)
+ )
+ )
+ self.assertEqual(
+ hello["extensions"],
+ [
+ {"type": 0, "bytes": 9, "names": [{"type": 0, "name": "test"}]},
+ {"type": 27, "bytes": 5, "values": [1, 2]},
+ {"type": 41, "bytes": 48, "identities": [5], "binders": [32]},
+ ],
+ )
+
+ def test_shuffle_keeps_grease_slots_and_share_group_relationships(self):
+ grease = bytes.fromhex("0a0a0000")
+ alpn = HELLO[78:]
+ first = extensions_hello(grease + alpn)
+ moved = extensions_hello(alpn + grease)
+ self.assertIn(
+ "extensions",
+ compare_client_hellos(first, moved, shuffle_extensions=True),
+ )
+ group = bytes.fromhex("000a000400020a0a")
+ share = bytes.fromhex("0033000700050a0a000100")
+ linked = extensions_hello(group + share)
+ unlinked = extensions_hello(group + share.replace(b"\x0a\x0a", b"\x1a\x1a"))
+ self.assertIn(
+ "grease_share_group_links", compare_client_hellos(linked, unlinked)
+ )
+
+ def test_rejects_truncated_duplicate_and_oversized_envelopes(self):
+ malformed = [HELLO[:size] for size in range(len(HELLO))]
+ malformed += [
+ HELLO + b"\x00",
+ b"\x00" * 65537,
+ extensions_hello(bytes.fromhex("0012000000120000")),
+ ]
+ for data in malformed:
+ with self.subTest(size=len(data)), self.assertRaises(ValueError):
+ parse_client_hello(data)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/scripts/tests/test_tls_observer.py b/scripts/tests/test_tls_observer.py
new file mode 100644
index 0000000..56dc340
--- /dev/null
+++ b/scripts/tests/test_tls_observer.py
@@ -0,0 +1,31 @@
+"""The observer is tested over injected byte streams, never host listeners."""
+
+import io
+import os
+import unittest
+from unittest.mock import patch
+
+from vcore_scripts.container_tls_observer import capture_client_hello, main
+
+
+class TlsObserverTest(unittest.TestCase):
+ def test_observer_refuses_host_execution_before_any_listener(self):
+ with patch.dict(os.environ, {}, clear=True), self.assertRaises(RuntimeError):
+ main()
+
+ def test_captures_fragmented_hello_and_retains_record_layout(self):
+ raw = bytes.fromhex("160301000301000016030300020100")
+ records, hello, layout = capture_client_hello(io.BytesIO(raw).read)
+ self.assertEqual(records, raw)
+ self.assertEqual(hello, bytes.fromhex("0100000100"))
+ self.assertEqual(
+ layout,
+ [
+ {"type": 22, "version": 0x0301, "bytes": 3},
+ {"type": 22, "version": 0x0303, "bytes": 2},
+ ],
+ )
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/scripts/tests/test_xhttp_gateway.py b/scripts/tests/test_xhttp_gateway.py
new file mode 100644
index 0000000..1529d2c
--- /dev/null
+++ b/scripts/tests/test_xhttp_gateway.py
@@ -0,0 +1,79 @@
+"""Offline external fixture contracts; real peers are container-only."""
+
+import json
+import unittest
+
+from vcore_scripts.container_quic_observer import summarize_trace
+from vcore_scripts.protocol_xhttp_gateway import gateway_config, sanitized_gateway_log
+
+
+class XhttpGatewayTest(unittest.TestCase):
+ def test_gateway_requires_client_auth_and_only_forwards_to_one_native_handler(self):
+ config = gateway_config("192.0.2.10")
+ self.assertTrue(config["admin"]["disabled"])
+ server = config["apps"]["http"]["servers"]["fixture"]
+ self.assertEqual(server["protocols"], ["h3"])
+ self.assertEqual(server["listen"], [":23000"])
+ self.assertTrue(server["automatic_https"]["disable"])
+ auth = server["tls_connection_policies"][0]["client_authentication"]
+ self.assertEqual(auth["mode"], "require_and_verify")
+ self.assertEqual(
+ auth["ca"],
+ {
+ "provider": "file",
+ "pem_files": ["/data/fixture/root.pem"],
+ },
+ )
+ handler = server["routes"][0]["handle"][0]
+ self.assertEqual(handler["handler"], "reverse_proxy")
+ self.assertEqual(handler["upstreams"], [{"dial": "192.0.2.10:23000"}])
+ self.assertEqual(handler["transport"]["versions"], ["h2c"])
+ # Negative flush_interval disables upstream cancellation on disconnect.
+ self.assertNotIn("flush_interval", handler)
+
+ def test_retained_gateway_log_has_protocol_evidence_without_request_identity(self):
+ retained = sanitized_gateway_log(
+ json.dumps(
+ {
+ "level": "warn",
+ "msg": "aborting with incomplete response",
+ "upstream": "192.0.2.10:23000",
+ "error": "context canceled",
+ "request": {
+ "remote_ip": "192.0.2.20",
+ "uri": "/private-session?token=secret",
+ "headers": {"Authorization": ["private-value"]},
+ "proto": "HTTP/3.0",
+ "method": "GET",
+ "tls": {"proto": "h3", "client_common_name": "private-name"},
+ },
+ }
+ )
+ )
+ evidence = json.loads(retained)
+ self.assertEqual(evidence["http_version"], "HTTP/3.0")
+ self.assertEqual(evidence["alpn"], "h3")
+ self.assertTrue(evidence["client_certificate_present"])
+ for forbidden in ("192.0.2", "private-", "secret", "Authorization"):
+ self.assertNotIn(forbidden, retained)
+
+ def test_native_trace_evidence_requires_local_certificate_rejection(self):
+ trace = {
+ "name": "transport:connection_closed",
+ "data": {
+ "initiator": "local",
+ "connection_error": "crypto_error_0x12d",
+ # Native quic-go records local TLS alerts with an empty reason.
+ "reason": "",
+ },
+ }
+ observed = summarize_trace("\x1e" + json.dumps(trace) + "\n")
+ self.assertEqual(
+ observed,
+ [{"tls_alert": "crypto_error_0x12d", "category": "certificate_expired"}],
+ )
+ trace["data"]["initiator"] = "remote"
+ self.assertEqual(summarize_trace(json.dumps(trace) + "\n"), [])
+ trace["data"]["initiator"] = "local"
+ trace["data"]["connection_error"] = "idle_timeout"
+ self.assertEqual(summarize_trace(json.dumps(trace) + "\n"), [])
diff --git a/scripts/tests/test_xhttp_peers.py b/scripts/tests/test_xhttp_peers.py
new file mode 100644
index 0000000..0fd5399
--- /dev/null
+++ b/scripts/tests/test_xhttp_peers.py
@@ -0,0 +1,61 @@
+"""Offline fixture contracts; no host listener is used."""
+
+import unittest
+
+from vcore_scripts.protocol_xhttp_peers import (
+ client_config,
+ identity_peer_config,
+ peer_config,
+)
+
+
+class XhttpPeerTest(unittest.TestCase):
+ def test_identity_probe_distinguishes_client_auth_from_root_trust(self):
+ mihomo = identity_peer_config("M", "cert", "key", "ca")
+ listener = mihomo["listeners"][0]
+ self.assertEqual(listener["client-auth-type"], "require-and-verify")
+ self.assertEqual(listener["client-auth-cert"], "ca")
+ xray = identity_peer_config("XR", "cert", "key", "ca")
+ tls = xray["inbounds"][0]["streamSettings"]["tlsSettings"]
+ self.assertEqual(
+ tls["certificates"][-1],
+ {
+ "certificateFile": "ca",
+ "usage": "verify",
+ },
+ )
+ self.assertEqual(tls["alpn"], ["h3"])
+
+ def test_http_versions_are_explicit_and_download_uses_the_same_handler(self):
+ for version in ("h1", "h2", "h3"):
+ config = client_config(
+ "192.0.2.1", "pin", version, "packet-up", download=True
+ )
+ node = config["proxies"][0]
+ self.assertEqual(node["alpn"], ["http/1.1" if version == "h1" else version])
+ self.assertEqual(node["xhttp-opts"]["download-settings"], {})
+ self.assertNotIn("skip-cert-verify", node)
+ self.assertEqual(config["listeners"][0]["proxy"], node["name"])
+
+ def test_mux_is_not_substituted_for_packet_encoding(self):
+ for protocol in ("h2mux", "smux", "yamux"):
+ config = client_config("192.0.2.1", "pin", "h2", "packet-up", mux=protocol)
+ node = config["proxies"][0]
+ self.assertEqual(node["smux"], {"enabled": True, "protocol": protocol})
+ self.assertEqual(node["packet-encoding"], "xudp")
+
+ def test_h3_bridge_does_not_replace_the_native_vless_decoder(self):
+ direct = peer_config("XR", "cert", "key")
+ bridge = peer_config("XR", "cert", "key", decoder="192.0.2.2")
+ self.assertEqual(direct["inbounds"][0]["protocol"], "vless")
+ self.assertEqual(bridge["inbounds"][0]["protocol"], "dokodemo-door")
+ self.assertEqual(bridge["inbounds"][0]["settings"]["port"], 23001)
+ self.assertEqual(
+ direct["inbounds"][0]["streamSettings"],
+ bridge["inbounds"][0]["streamSettings"],
+ )
+ for config in (direct, bridge):
+ self.assertEqual(len(config["inbounds"]), 1)
+ stream = config["inbounds"][0]["streamSettings"]
+ self.assertEqual(stream["tlsSettings"]["alpn"], ["h3"])
+ self.assertEqual(stream["xhttpSettings"]["mode"], "auto")
diff --git a/src/config/ech.rs b/src/config/ech.rs
new file mode 100644
index 0000000..7c93ab1
--- /dev/null
+++ b/src/config/ech.rs
@@ -0,0 +1,170 @@
+//! Static ECH configuration admission shared by both TLS backends. In
+//! particular, BoringSSL otherwise silently skips unsupported configurations.
+use super::*;
+
+#[derive(Clone, PartialEq, Eq)]
+pub struct StaticEchConfig(Vec);
+
+impl std::fmt::Debug for StaticEchConfig {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.debug_struct("StaticEchConfig").finish_non_exhaustive()
+ }
+}
+
+impl StaticEchConfig {
+ /// Keeps the first mutually supported config's exact wire encoding. No
+ /// backend can skip an earlier unsupported entry and expose the inner SNI.
+ pub fn from_config_list(bytes: &[u8]) -> Result {
+ if bytes.len() > 65_537 {
+ return invalid("ECH config list exceeds the wire bound");
+ }
+ let mut reader = Reader(bytes);
+ let list = reader.vector16()?;
+ reader.end()?;
+ let mut configs = Reader(list);
+ let mut selected = None;
+ while !configs.0.is_empty() {
+ let start = configs.0;
+ let version = configs.u16()?;
+ let contents = configs.vector16()?;
+ if version == 0xfe0d && supported(contents)? && selected.is_none() {
+ selected = Some(&start[..4 + contents.len()]);
+ }
+ }
+ let selected = selected.ok_or_else(|| {
+ VCoreError::InvalidConfig("ECH has no compatible configuration".into())
+ })?;
+ let mut wire = (selected.len() as u16).to_be_bytes().to_vec();
+ wire.extend_from_slice(selected);
+ Ok(Self(wire))
+ }
+
+ #[cfg(feature = "tls-fingerprint")]
+ pub(crate) fn as_bytes(&self) -> &[u8] {
+ &self.0
+ }
+}
+
+fn supported(bytes: &[u8]) -> Result {
+ let mut r = Reader(bytes);
+ r.take(1)?; // config_id
+ let kem = r.u16()?;
+ let key = r.vector16()?;
+ let suites = r.vector16()?;
+ if suites.is_empty() || !suites.len().is_multiple_of(4) {
+ return invalid("invalid ECH cipher suites");
+ }
+ let compatible_suite = suites.as_chunks::<4>().0.iter().any(|suite| {
+ suite[..2] == [0, 1] && matches!(u16::from_be_bytes([suite[2], suite[3]]), 1..=3)
+ });
+ r.take(1)?; // maximum_name_length
+ let name_len = usize::from(r.take(1)?[0]);
+ let name = r.take(name_len)?;
+ let mut extensions = Reader(r.vector16()?);
+ r.end()?;
+ let mut seen = std::collections::BTreeSet::new();
+ let mut compatible_extensions = true;
+ while !extensions.0.is_empty() {
+ let kind = extensions.u16()?;
+ extensions.vector16()?;
+ compatible_extensions &= kind & 0x8000 == 0 && seen.insert(kind);
+ }
+ Ok(kem == 0x0020
+ && key.len() == 32
+ && compatible_suite
+ && compatible_extensions
+ && valid_public_name(name))
+}
+
+fn valid_public_name(name: &[u8]) -> bool {
+ // Match the stricter fixed BoringSSL LDH/IP-lookalike admission rules.
+ if name.is_empty() || name.len() > 253 {
+ return false;
+ }
+ if name.split(|b| *b == b'.').any(|label| {
+ label.is_empty()
+ || label.len() > 63
+ || label.first() == Some(&b'-')
+ || label.last() == Some(&b'-')
+ || !label
+ .iter()
+ .all(|b| b.is_ascii_alphanumeric() || *b == b'-')
+ }) {
+ return false;
+ }
+ let last = name.rsplit(|b| *b == b'.').next().unwrap_or_default();
+ !last.iter().all(u8::is_ascii_digit)
+ && !(last.len() >= 2
+ && last[0] == b'0'
+ && matches!(last[1], b'x' | b'X')
+ && last[2..].iter().all(u8::is_ascii_hexdigit))
+}
+
+struct Reader<'a>(&'a [u8]);
+impl<'a> Reader<'a> {
+ fn take(&mut self, n: usize) -> Result<&'a [u8]> {
+ let Some((head, tail)) = self.0.split_at_checked(n) else {
+ return invalid("invalid ECH config list");
+ };
+ self.0 = tail;
+ Ok(head)
+ }
+ fn u16(&mut self) -> Result {
+ let bytes = self.take(2)?;
+ Ok(u16::from_be_bytes([bytes[0], bytes[1]]))
+ }
+ fn vector16(&mut self) -> Result<&'a [u8]> {
+ let len = usize::from(self.u16()?);
+ self.take(len)
+ }
+ fn end(self) -> Result<()> {
+ if !self.0.is_empty() {
+ return invalid("invalid ECH config list");
+ }
+ Ok(())
+ }
+}
+
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(super) struct RawEch {
+ #[serde(default)]
+ enable: bool,
+ #[serde(default, deserialize_with = "deserialize_present_option")]
+ config: Option,
+}
+
+impl std::fmt::Debug for RawEch {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.debug_struct("RawEch").finish_non_exhaustive()
+ }
+}
+
+impl RawEch {
+ pub(super) fn normalize(self) -> Result> {
+ if !self.enable {
+ if self.config.as_ref().is_some_and(|value| !value.is_empty()) {
+ return invalid("ECH config requires enable=true");
+ }
+ return Ok(None);
+ }
+ let encoded = self.config.ok_or_else(|| {
+ VCoreError::InvalidConfig("static ECH requires an explicit config".into())
+ })?;
+ if encoded.len() > 87_384 {
+ return invalid("ECH config exceeds the wire bound");
+ }
+ let wire = base64::engine::general_purpose::STANDARD
+ .decode(encoded)
+ .map_err(|_| VCoreError::InvalidConfig("invalid ECH Base64 config".into()))?;
+ StaticEchConfig::from_config_list(&wire).map(Some)
+ }
+}
+
+pub(super) fn deserialize<'de, D>(deserializer: D) -> std::result::Result, D::Error>
+where
+ D: Deserializer<'de>,
+{
+ deserialize_present_map(deserializer)
+ .map_err(|_| serde::de::Error::custom("invalid static ECH options"))
+}
diff --git a/src/config/fingerprint_tests.rs b/src/config/fingerprint_tests.rs
new file mode 100644
index 0000000..c916994
--- /dev/null
+++ b/src/config/fingerprint_tests.rs
@@ -0,0 +1,236 @@
+use super::*;
+
+fn yaml(protocol: &str, fields: &str) -> String {
+ let auth = match protocol {
+ "anytls" | "trojan" => "password: fixture",
+ "vmess" => {
+ "uuid: 00000000-0000-4000-8000-000000000001\n alterId: 0\n cipher: auto\n tls: true"
+ }
+ "vless" => "uuid: 00000000-0000-4000-8000-000000000001\n tls: true",
+ _ => unreachable!(),
+ };
+ format!("port: 1080\nrules: [MATCH,p]\nproxies:\n - name: p\n type: {protocol}\n server: example.com\n port: 443\n {auth}\n {fields}\n").replace("rules: [MATCH,p]", "rules: ['MATCH,p']")
+}
+
+fn profile(config: &Config) -> Option {
+ match &config.proxies[0].protocol {
+ ProxyProtocol::AnyTls(p) => p.tls.client_fingerprint,
+ ProxyProtocol::Trojan(p) => p.tls.client_fingerprint,
+ ProxyProtocol::Vmess(p) => p.tls.as_ref().unwrap().client_fingerprint,
+ ProxyProtocol::Vless(p) => match &p.security {
+ SecurityConfig::Tls(tls) => tls.client_fingerprint,
+ SecurityConfig::Reality(reality) => reality.client_fingerprint,
+ _ => panic!("expected TLS"),
+ },
+ _ => unreachable!(),
+ }
+}
+
+#[test]
+fn named_fingerprint_is_strict_and_independent_of_certificate_pins() {
+ for protocol in ["anytls", "trojan", "vmess", "vless"] {
+ for (value, expected) in [
+ ("chrome120", Some(ClientFingerprint::Chrome120)),
+ ("none", None),
+ ("\"\"", None),
+ ] {
+ let config = Config::parse_yaml(
+ yaml(
+ protocol,
+ &format!(
+ "client-fingerprint: {value}\n fingerprint: {}",
+ "aa".repeat(32)
+ ),
+ )
+ .as_bytes(),
+ )
+ .unwrap();
+ assert_eq!(profile(&config), expected);
+ }
+ assert_eq!(
+ profile(&Config::parse_yaml(yaml(protocol, "").as_bytes()).unwrap()),
+ None
+ );
+ for value in [
+ "Chrome120",
+ "Chrome",
+ "NONE",
+ "chrome133",
+ "safari16.0",
+ "ios",
+ "android",
+ "edge",
+ "random",
+ "randomized",
+ "chrome_psk",
+ "chrome_pq",
+ "null",
+ "1",
+ "{}",
+ "[]",
+ "true",
+ "secret-unknown-profile",
+ ] {
+ let error = Config::parse_yaml(
+ yaml(protocol, &format!("client-fingerprint: {value}")).as_bytes(),
+ )
+ .unwrap_err();
+ assert!(!error.to_string().contains("secret-unknown-profile"));
+ }
+ }
+ for protocol in ["vless", "vmess"] {
+ for value in ["chrome", "firefox", "safari", "none", "\"\""] {
+ assert!(
+ Config::parse_yaml(
+ yaml(protocol, &format!("client-fingerprint: {value}"))
+ .replace("tls: true", "tls: false")
+ .as_bytes()
+ )
+ .is_err()
+ );
+ }
+ }
+}
+
+#[test]
+fn selected_names_resolve_to_four_distinct_templates_and_only_documented_aliases() {
+ for protocol in ["anytls", "trojan", "vmess", "vless"] {
+ let mut templates = Vec::new();
+ for name in ["chrome", "chrome120", "firefox", "safari"] {
+ let config = Config::parse_yaml(
+ yaml(protocol, &format!("client-fingerprint: {name}")).as_bytes(),
+ )
+ .unwrap();
+ let selected = profile(&config).expect("enabled profile");
+ assert!(
+ !templates.contains(&selected),
+ "{name} cannot reuse another template"
+ );
+ templates.push(selected);
+ }
+ for (alias, template) in [("firefox120", templates[2]), ("safari16", templates[3])] {
+ let config = Config::parse_yaml(
+ yaml(protocol, &format!("client-fingerprint: {alias}")).as_bytes(),
+ )
+ .unwrap();
+ assert_eq!(profile(&config), Some(template));
+ }
+ }
+}
+
+#[test]
+fn download_fingerprint_inherits_and_can_be_cleared_independently() {
+ for (name, template) in [
+ ("chrome120", ClientFingerprint::Chrome120),
+ ("chrome", ClientFingerprint::Chrome133),
+ ("firefox", ClientFingerprint::Firefox120),
+ ("safari", ClientFingerprint::Safari16),
+ ] {
+ let base = yaml(
+ "vless",
+ &format!(
+ "network: xhttp\n client-fingerprint: {name}\n xhttp-opts:\n path: /fixture\n mode: stream-up\n download-settings:\n server: download.example.com"
+ ),
+ );
+ for (extra, expected) in [
+ ("", Some(template)),
+ ("\n client-fingerprint: \"\"", None),
+ ("\n client-fingerprint: none", None),
+ (
+ "\n client-fingerprint: chrome",
+ Some(ClientFingerprint::Chrome133),
+ ),
+ (
+ "\n client-fingerprint: chrome120",
+ Some(ClientFingerprint::Chrome120),
+ ),
+ (
+ "\n client-fingerprint: firefox120",
+ Some(ClientFingerprint::Firefox120),
+ ),
+ (
+ "\n client-fingerprint: safari16",
+ Some(ClientFingerprint::Safari16),
+ ),
+ ] {
+ let text = format!("{}{extra}\n", base.trim_end());
+ let config = Config::parse_yaml(text.as_bytes()).unwrap();
+ assert_eq!(profile(&config), Some(template));
+ let ProxyProtocol::Vless(vless) = &config.proxies[0].protocol else {
+ unreachable!()
+ };
+ let VlessTransport::Xhttp(xhttp) = &vless.transport else {
+ unreachable!()
+ };
+ let SecurityConfig::Tls(tls) = &xhttp.download.as_ref().unwrap().security else {
+ unreachable!()
+ };
+ assert_eq!(tls.client_fingerprint, expected);
+ }
+ assert!(
+ Config::parse_yaml(
+ yaml(
+ "vless",
+ &format!("network: xhttp\n alpn: [h3]\n client-fingerprint: {name}")
+ )
+ .as_bytes()
+ )
+ .is_err()
+ );
+ assert!(Config::parse_yaml(format!("{} alpn: [h3]\n", base).as_bytes()).is_err());
+ for clear in ["none", "\"\""] {
+ for security in ["alpn: [h3]", "tls: false"] {
+ assert!(
+ Config::parse_yaml(
+ format!("{base} {security}\n client-fingerprint: {clear}\n")
+ .as_bytes()
+ )
+ .is_ok()
+ );
+ }
+ }
+ for value in [
+ "null",
+ "true",
+ "1",
+ "[]",
+ "{}",
+ "Chrome",
+ "chrome133",
+ "safari16.0",
+ ] {
+ assert!(
+ Config::parse_yaml(
+ format!("{base} client-fingerprint: {value}\n").as_bytes()
+ )
+ .is_err()
+ );
+ }
+ assert!(Config::parse_yaml(format!("{} tls: false\n", base).as_bytes()).is_err());
+ }
+}
+
+#[test]
+fn reality_accepts_named_profile_without_admitting_certificate_policy() {
+ for (name, expected) in [
+ ("chrome120", Some(ClientFingerprint::Chrome120)),
+ ("chrome", Some(ClientFingerprint::Chrome133)),
+ ("firefox", Some(ClientFingerprint::Firefox120)),
+ ("safari", Some(ClientFingerprint::Safari16)),
+ ("none", None),
+ ("\"\"", None),
+ ] {
+ let fields = format!(
+ "client-fingerprint: {name}\n reality-opts:\n public-key: {}",
+ URL_SAFE_NO_PAD.encode([7; 32])
+ );
+ let config = Config::parse_yaml(yaml("vless", &fields).as_bytes()).unwrap();
+ assert_eq!(profile(&config), expected);
+ assert!(
+ Config::parse_yaml(
+ yaml("vless", &format!("skip-cert-verify: true\n {fields}")).as_bytes()
+ )
+ .is_err()
+ );
+ }
+}
diff --git a/src/config/hysteria2.rs b/src/config/hysteria2.rs
new file mode 100644
index 0000000..b2bb6be
--- /dev/null
+++ b/src/config/hysteria2.rs
@@ -0,0 +1,294 @@
+use serde::Deserialize;
+
+use super::{
+ ProxyProtocol, TlsCertificatePolicy, TlsConfig, TlsIdentityPem, deserialize_present_option,
+ invalid, validate_host, validate_port,
+};
+use crate::Result;
+
+#[derive(Clone, PartialEq, Eq)]
+pub struct Hysteria2OutboundConfig {
+ pub address: String,
+ pub port: u16,
+ pub password: String,
+ pub tls: TlsConfig,
+ pub up: u64,
+ pub down: u64,
+ pub udp_mtu: u16,
+ pub obfs_password: Option,
+ pub hopping: Option,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Hysteria2Hopping {
+ pub ports: Vec,
+ pub min_seconds: u32,
+ pub max_seconds: u32,
+}
+
+impl std::fmt::Debug for Hysteria2OutboundConfig {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.debug_struct("Hysteria2OutboundConfig")
+ .finish_non_exhaustive()
+ }
+}
+
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(super) struct RawHysteria2 {
+ name: String,
+ server: String,
+ #[serde(default, deserialize_with = "deserialize_present_option")]
+ port: Option,
+ #[serde(default)]
+ password: String,
+ #[serde(default)]
+ udp: bool,
+ #[serde(default, deserialize_with = "deserialize_present_option")]
+ sni: Option,
+ #[serde(default, deserialize_with = "deserialize_present_option")]
+ alpn: Option>,
+ #[serde(rename = "skip-cert-verify", default)]
+ skip_cert_verify: bool,
+ #[serde(default, deserialize_with = "deserialize_present_option")]
+ fingerprint: Option,
+ #[serde(
+ rename = "certificate",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ certificate: Option,
+ #[serde(
+ rename = "private-key",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ private_key: Option,
+ #[serde(
+ rename = "dialer-proxy",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ dialer_proxy: Option,
+ #[serde(default, deserialize_with = "deserialize_present_option")]
+ up: Option,
+ #[serde(default, deserialize_with = "deserialize_present_option")]
+ down: Option,
+ #[serde(rename = "udp-mtu", default)]
+ udp_mtu: u16,
+ #[serde(default, deserialize_with = "deserialize_present_option")]
+ obfs: Option,
+ #[serde(
+ rename = "obfs-password",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ obfs_password: Option,
+ #[serde(default, deserialize_with = "deserialize_present_option")]
+ ports: Option,
+ #[serde(
+ rename = "hop-interval",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ hop_interval: Option,
+}
+
+#[derive(Deserialize)]
+#[serde(untagged)]
+enum NumberOrText {
+ Number(u64),
+ Text(String),
+}
+
+impl std::fmt::Debug for RawHysteria2 {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.debug_struct("RawHysteria2").finish_non_exhaustive()
+ }
+}
+
+impl RawHysteria2 {
+ pub(super) fn normalize(self) -> Result<(String, Option, bool, ProxyProtocol)> {
+ if !cfg!(feature = "outbound-hysteria2") {
+ return invalid("Hysteria2 outbound support is disabled at build time");
+ }
+ validate_host(&self.server, "Hysteria2 server")?;
+ if let Some(port) = self.port {
+ validate_port(port, "Hysteria2")?;
+ }
+ let hopping = self
+ .ports
+ .map(|ports| {
+ let ports = parse_ports(&ports)?;
+ let (min_seconds, max_seconds) = parse_interval(self.hop_interval.as_ref())?;
+ Ok::<_, crate::VCoreError>(Hysteria2Hopping {
+ ports,
+ min_seconds,
+ max_seconds,
+ })
+ })
+ .transpose()?;
+ if hopping.is_none() && self.hop_interval.is_some() {
+ return invalid("Hysteria2 hop-interval requires ports");
+ }
+ let port = match &hopping {
+ Some(hopping) => hopping.ports[0],
+ None => self.port.ok_or_else(|| {
+ crate::VCoreError::InvalidConfig("Hysteria2 requires port or ports".into())
+ })?,
+ };
+ // The complete auth header section is bounded to 16 KiB. Validate the
+ // raw value, without trimming credentials or printing them on failure.
+ if self.password.len() > 8192
+ || http::HeaderValue::from_bytes(self.password.as_bytes()).is_err()
+ {
+ return invalid("invalid or over-limit Hysteria2 authentication header");
+ }
+ let obfs_password = match (self.obfs.as_deref(), self.obfs_password) {
+ (None, None) => None,
+ (Some("salamander"), Some(password)) if !password.is_empty() => Some(password),
+ _ => return invalid("Hysteria2 Salamander requires obfs and a nonempty obfs-password"),
+ };
+ let server_name = self.sni.unwrap_or_else(|| self.server.clone());
+ validate_host(&server_name, "Hysteria2 sni")?;
+ let mut alpn = self.alpn.unwrap_or_default();
+ if alpn.is_empty() {
+ alpn.push("h3".into());
+ }
+ if alpn.iter().any(|item| item.is_empty() || item.len() > 255)
+ || alpn.iter().map(|item| item.len() + 1).sum::() > 65533
+ {
+ return invalid("invalid Hysteria2 ALPN list");
+ }
+ let identity = match (self.certificate, self.private_key) {
+ (None, None) => None,
+ (Some(certificate), Some(private_key)) => {
+ #[cfg(feature = "outbound-hysteria2")]
+ crate::security::TlsClientIdentity::from_pem(&certificate, &private_key).map_err(
+ |_| {
+ crate::VCoreError::InvalidConfig("invalid Hysteria2 client identity".into())
+ },
+ )?;
+ Some(TlsIdentityPem {
+ certificate,
+ private_key,
+ })
+ }
+ _ => return invalid("Hysteria2 certificate and private-key must be paired"),
+ };
+ let fingerprint = self
+ .fingerprint
+ .map(|pin| {
+ super::vless::parse_pin(&pin).map_err(|_| {
+ crate::VCoreError::InvalidConfig(
+ "invalid Hysteria2 certificate fingerprint".into(),
+ )
+ })
+ })
+ .transpose()?;
+ let udp_mtu = if self.udp_mtu == 0 {
+ 1197
+ } else {
+ self.udp_mtu
+ };
+ if udp_mtu < 64 {
+ return invalid("Hysteria2 udp-mtu must be 0 or 64..65535");
+ }
+ Ok((
+ self.name,
+ self.dialer_proxy,
+ self.udp,
+ ProxyProtocol::Hysteria2(Hysteria2OutboundConfig {
+ address: self.server,
+ port,
+ password: self.password,
+ tls: TlsConfig {
+ ech: None,
+ client_fingerprint: None,
+ server_name,
+ alpn: alpn.into_iter().map(String::into_bytes).collect(),
+ tls13_only: true,
+ required_alpn: None,
+ certificate: TlsCertificatePolicy {
+ skip_cert_verify: self.skip_cert_verify,
+ fingerprint,
+ verification_name: None,
+ },
+ identity,
+ },
+ up: parse_rate(self.up)?,
+ down: parse_rate(self.down)?,
+ udp_mtu,
+ obfs_password,
+ hopping,
+ }),
+ ))
+ }
+}
+
+fn parse_rate(raw: Option) -> Result {
+ let text = match raw {
+ None => return Ok(0),
+ Some(NumberOrText::Number(value)) => format!("{value}"),
+ Some(NumberOrText::Text(value)) => value.trim().to_owned(),
+ };
+ let end = text.bytes().take_while(u8::is_ascii_digit).count();
+ let value = text[..end]
+ .parse::()
+ .map_err(|_| crate::VCoreError::InvalidConfig("invalid Hysteria2 bandwidth".into()))?;
+ let unit = text[end..].trim();
+ let (factor, divisor) = match unit {
+ "" | "Mbps" => (1_000_000_u64, 8),
+ "bps" => (1, 8),
+ "Kbps" => (1000, 8),
+ "Gbps" => (1_000_000_000, 8),
+ "Tbps" => (1_000_000_000_000, 8),
+ "Bps" => (1, 1),
+ "KBps" => (1000, 1),
+ "MBps" => (1_000_000, 1),
+ "GBps" => (1_000_000_000, 1),
+ "TBps" => (1_000_000_000_000, 1),
+ _ => return invalid("invalid Hysteria2 bandwidth unit"),
+ };
+ value
+ .checked_mul(factor)
+ .map(|bytes| bytes / divisor)
+ .ok_or_else(|| crate::VCoreError::InvalidConfig("Hysteria2 bandwidth overflows".into()))
+}
+
+fn decimal(value: &str) -> Result {
+ if value.is_empty() || !value.bytes().all(|byte| byte.is_ascii_digit()) {
+ return invalid("invalid Hysteria2 integer range");
+ }
+ value
+ .parse()
+ .map_err(|_| crate::VCoreError::InvalidConfig("Hysteria2 integer range overflows".into()))
+}
+
+fn parse_ports(value: &str) -> Result> {
+ let mut ports = std::collections::BTreeSet::new();
+ for item in value.split(',') {
+ let item = item.trim();
+ let (start, end) = item.split_once('-').unwrap_or((item, item));
+ let (start, end) = (decimal(start)?, decimal(end)?);
+ if start == 0 || start > end || end > 65535 {
+ return invalid("invalid Hysteria2 ports");
+ }
+ ports.extend((start..=end).map(|port| port as u16));
+ }
+ Ok(ports.into_iter().collect())
+}
+
+fn parse_interval(value: Option<&NumberOrText>) -> Result<(u32, u32)> {
+ let text = match value {
+ None => return Ok((30, 30)),
+ Some(NumberOrText::Number(value)) => value.to_string(),
+ Some(NumberOrText::Text(value)) => value.clone(),
+ };
+ let (start, end) = text.split_once('-').unwrap_or((&text, &text));
+ let (start, end) = (decimal(start)?, decimal(end)?);
+ if start < 5 || start > end {
+ return invalid("Hysteria2 hop-interval requires 5 <= min <= max <= 4294967295 seconds");
+ }
+ Ok((start, end))
+}
diff --git a/src/config/jls.rs b/src/config/jls.rs
new file mode 100644
index 0000000..a1867bd
--- /dev/null
+++ b/src/config/jls.rs
@@ -0,0 +1,80 @@
+use super::*;
+
+/// JLS identity is independent of WebPKI; the native TLS handshake still verifies
+/// CertificateVerify and Finished. Each transport leg owns its credentials.
+#[derive(Clone, PartialEq, Eq)]
+pub struct JlsConfig {
+ pub tls: TlsConfig,
+ pub username: String,
+ pub password: String,
+}
+
+impl std::fmt::Debug for JlsConfig {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.debug_struct("JlsConfig")
+ .field("tls", &self.tls)
+ .finish_non_exhaustive()
+ }
+}
+
+impl JlsConfig {
+ pub(crate) fn validate(&self) -> Result<()> {
+ for value in [&self.username, &self.password] {
+ if value.is_empty() || value.len() > 65_535 {
+ return invalid("JLS credentials must each contain 1..65535 bytes");
+ }
+ }
+ if self.tls.certificate != TlsCertificatePolicy::default()
+ || self.tls.identity.is_some()
+ || self.tls.ech.is_some()
+ {
+ return invalid("JLS cannot use standard certificate policy or client identity");
+ }
+ Ok(())
+ }
+}
+
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(super) struct RawJls {
+ #[serde(default, deserialize_with = "deserialize_present_option")]
+ username: Option,
+ #[serde(default, deserialize_with = "deserialize_present_option")]
+ password: Option,
+}
+
+impl std::fmt::Debug for RawJls {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.debug_struct("RawJls").finish_non_exhaustive()
+ }
+}
+
+impl RawJls {
+ pub(super) fn is_empty(&self) -> bool {
+ self.username.is_none() && self.password.is_none()
+ }
+
+ pub(super) fn normalize(self, tls: TlsConfig) -> Result {
+ let (Some(username), Some(password)) = (self.username, self.password) else {
+ return invalid("JLS requires both username and password");
+ };
+ let config = JlsConfig {
+ tls,
+ username,
+ password,
+ };
+ config.validate()?;
+ Ok(config)
+ }
+}
+
+pub(super) fn deserialize<'de, D>(deserializer: D) -> std::result::Result, D::Error>
+where
+ D: Deserializer<'de>,
+{
+ // Serde's type/unknown-field errors can echo a supplied numeric secret or
+ // an entire malformed credential object. Keep the strict map decoder but
+ // do not expose its input-bearing error through Config or Invoke.
+ deserialize_present_map(deserializer)
+ .map_err(|_| serde::de::Error::custom("invalid JLS credential object"))
+}
diff --git a/src/config/measure.rs b/src/config/measure.rs
index c90616a..e7bc54a 100644
--- a/src/config/measure.rs
+++ b/src/config/measure.rs
@@ -101,6 +101,29 @@ impl RawMeasureConfig {
#[cfg(test)]
mod tests {
+ #[test]
+ fn measurement_rejects_future_protocols_and_oversized_documents() {
+ let _case = crate::resources::case_events::Case::new(
+ "FOUNDATIONS-SCHEMA",
+ "measurement_rejects_future_protocols_and_oversized_documents",
+ );
+ let yaml =
+ b"proxies:\n - name: node\n type: wireguard\n server: example.com\n port: 443\n";
+ assert!(super::MeasureConfig::parse_yaml(yaml).is_err());
+ assert!(
+ super::MeasureConfig::parse_yaml(&vec![b'x'; super::MAX_CONFIG_BYTES + 1]).is_err()
+ );
+ }
+
+ #[test]
+ fn measurement_hysteria2_admission_matches_the_protocol_feature() {
+ let yaml =
+ b"proxies:\n - name: node\n type: hysteria2\n server: example.com\n port: 443\n";
+ assert_eq!(
+ super::MeasureConfig::parse_yaml(yaml).is_ok(),
+ cfg!(feature = "outbound-hysteria2")
+ );
+ }
use super::*;
const NODE: &str = r#"
diff --git a/src/config/mod.rs b/src/config/mod.rs
index 4239b85..bde6130 100644
--- a/src/config/mod.rs
+++ b/src/config/mod.rs
@@ -19,8 +19,23 @@ use crate::{Result, VCoreError};
mod credentials;
pub use credentials::{ProxyAccess, ProxyCredentials};
+mod ech;
+pub use ech::StaticEchConfig;
+mod hysteria2;
+pub use hysteria2::{Hysteria2Hopping, Hysteria2OutboundConfig};
+mod jls;
+pub use jls::JlsConfig;
mod shadowsocks;
pub use shadowsocks::{ShadowsocksCipher, ShadowsocksOutboundConfig};
+mod trojan;
+pub use trojan::{TrojanOutboundConfig, TrojanTransport};
+mod vless;
+pub use vless::{GrpcOptions, SingMuxConfig, SingMuxProtocol, VlessStreamOptions};
+pub(crate) mod xhttp;
+pub use xhttp::{XHttpHeaders, XHttpRequestOptions, XHttpReuseConfig, XHttpVersion};
+mod vmess;
+pub use vmess::StreamTransport as VmessTransport;
+pub use vmess::{StreamTransport, VmessCipher, VmessOutboundConfig, VmessPacketEncoding};
#[cfg(feature = "ffi")]
mod measure;
@@ -286,6 +301,9 @@ pub struct ProxyConfig {
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ProxyProtocol {
+ Hysteria2(Hysteria2OutboundConfig),
+ Vmess(VmessOutboundConfig),
+ Trojan(TrojanOutboundConfig),
Vless(VlessOutboundConfig),
Socks5(Socks5OutboundConfig),
AnyTls(AnyTlsOutboundConfig),
@@ -296,6 +314,9 @@ impl ProxyConfig {
#[must_use]
pub fn address(&self) -> &str {
match &self.protocol {
+ ProxyProtocol::Hysteria2(config) => &config.address,
+ ProxyProtocol::Vmess(config) => &config.address,
+ ProxyProtocol::Trojan(config) => &config.address,
ProxyProtocol::Vless(config) => &config.address,
ProxyProtocol::Socks5(config) => &config.address,
ProxyProtocol::AnyTls(config) => &config.address,
@@ -306,6 +327,9 @@ impl ProxyConfig {
#[must_use]
pub const fn port(&self) -> u16 {
match &self.protocol {
+ ProxyProtocol::Hysteria2(config) => config.port,
+ ProxyProtocol::Vmess(config) => config.port,
+ ProxyProtocol::Trojan(config) => config.port,
ProxyProtocol::Vless(config) => config.port,
ProxyProtocol::Socks5(config) => config.port,
ProxyProtocol::AnyTls(config) => config.port,
@@ -314,7 +338,7 @@ impl ProxyConfig {
}
}
-#[derive(Debug, Clone, PartialEq, Eq)]
+#[derive(Clone, PartialEq, Eq)]
pub struct VlessOutboundConfig {
pub address: String,
pub port: u16,
@@ -322,7 +346,45 @@ pub struct VlessOutboundConfig {
pub encryption: VlessEncryption,
pub flow: String,
pub security: SecurityConfig,
- pub xhttp: XHttpConfig,
+ pub transport: VlessTransport,
+ pub packet_encoding: VlessPacketEncoding,
+ pub stream_options: VlessStreamOptions,
+}
+
+impl std::fmt::Debug for VlessOutboundConfig {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.debug_struct("VlessOutboundConfig")
+ .finish_non_exhaustive()
+ }
+}
+
+impl VlessOutboundConfig {
+ pub fn xhttp(&self) -> Option<&XHttpConfig> {
+ match &self.transport {
+ VlessTransport::Xhttp(config) => Some(config),
+ VlessTransport::Stream(_) => None,
+ }
+ }
+ pub fn download(&self) -> Option<&XHttpDownloadConfig> {
+ self.xhttp().and_then(|config| config.download.as_deref())
+ }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum VlessTransport {
+ Stream(StreamTransport),
+ Xhttp(Box),
+}
+
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Deserialize)]
+pub enum VlessPacketEncoding {
+ #[default]
+ #[serde(rename = "xudp")]
+ Xudp,
+ #[serde(rename = "none")]
+ Raw,
+ #[serde(rename = "packetaddr", alias = "packet")]
+ PacketAddr,
}
#[derive(Debug, Clone, PartialEq, Eq)]
@@ -344,11 +406,44 @@ pub struct AnyTlsOutboundConfig {
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct AnyTlsCertificatePolicy {
+ pub client_fingerprint: Option,
pub alpn: Vec>,
pub skip_cert_verify: bool,
pub fingerprint: Option<[u8; 32]>,
}
+/// A version-pinned ClientHello profile, independent of certificate pins.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ClientFingerprint {
+ Chrome120,
+ Chrome133,
+ Firefox120,
+ Safari16,
+}
+
+fn parse_client_fingerprint(value: Option<&str>) -> Result> {
+ match value {
+ None | Some("" | "none") => Ok(None),
+ Some(_) if !cfg!(feature = "tls-fingerprint") => {
+ invalid("client-fingerprint is not compiled in")
+ }
+ Some("chrome") => Ok(Some(ClientFingerprint::Chrome133)),
+ Some("chrome120") => Ok(Some(ClientFingerprint::Chrome120)),
+ Some("firefox" | "firefox120") => Ok(Some(ClientFingerprint::Firefox120)),
+ Some("safari" | "safari16") => Ok(Some(ClientFingerprint::Safari16)),
+ Some(_) => invalid("unsupported client-fingerprint"),
+ }
+}
+
+#[cfg(all(
+ test,
+ feature = "outbound-anytls",
+ feature = "outbound-trojan",
+ feature = "outbound-vmess",
+ feature = "outbound-vless"
+))]
+mod fingerprint_tests;
+
impl std::fmt::Debug for AnyTlsOutboundConfig {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter
@@ -360,37 +455,130 @@ impl std::fmt::Debug for AnyTlsOutboundConfig {
}
}
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[derive(Clone, PartialEq, Eq)]
pub enum VlessEncryption {
None,
+ MlKem768X25519Plus(String),
+}
+impl std::fmt::Debug for VlessEncryption {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.write_str(match self {
+ Self::None => "None",
+ Self::MlKem768X25519Plus(_) => "MlKem768X25519Plus { .. }",
+ })
+ }
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SecurityConfig {
+ None,
Tls(TlsConfig),
Reality(RealityConfig),
+ Jls(JlsConfig),
}
impl SecurityConfig {
+ fn client_fingerprint(&self) -> Option {
+ match self {
+ Self::None => None,
+ Self::Tls(config) => config.client_fingerprint,
+ Self::Reality(config) => config.client_fingerprint,
+ Self::Jls(config) => config.tls.client_fingerprint,
+ }
+ }
#[must_use]
pub fn server_name(&self) -> &str {
match self {
+ Self::None => "",
Self::Tls(config) => &config.server_name,
Self::Reality(config) => &config.server_name,
+ Self::Jls(config) => &config.tls.server_name,
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TlsConfig {
+ pub ech: Option,
+ pub client_fingerprint: Option,
pub server_name: String,
+ pub alpn: Vec>,
+ pub tls13_only: bool,
+ pub required_alpn: Option>,
+ pub certificate: TlsCertificatePolicy,
+ pub identity: Option,
+}
+
+/// Data-only certificate policy, also available in builds without TLS IO.
+/// A matching leaf pin is the trust decision; a non-leaf pin still verifies
+/// the chain and name. Explicit pin/name checks precede `skip_cert_verify`.
+#[derive(Clone, Default, PartialEq, Eq)]
+pub struct TlsCertificatePolicy {
+ pub verification_name: Option,
+ pub skip_cert_verify: bool,
+ pub fingerprint: Option<[u8; 32]>,
+}
+
+impl std::fmt::Debug for TlsCertificatePolicy {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.debug_struct("TlsCertificatePolicy")
+ .field("explicit_name", &self.verification_name.is_some())
+ .field("skip_cert_verify", &self.skip_cert_verify)
+ .field("pinned", &self.fingerprint.is_some())
+ .finish()
+ }
+}
+
+#[derive(Clone, PartialEq, Eq)]
+pub struct TlsIdentityPem {
+ pub certificate: String,
+ pub private_key: String,
+}
+impl std::fmt::Debug for TlsIdentityPem {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.debug_struct("TlsIdentityPem").finish_non_exhaustive()
+ }
+}
+
+impl TlsConfig {
+ pub fn xhttp(server_name: String) -> Self {
+ Self {
+ ech: None,
+ client_fingerprint: None,
+ server_name,
+ alpn: vec![b"h2".to_vec()],
+ tls13_only: true,
+ required_alpn: Some(b"h2".to_vec()),
+ certificate: Default::default(),
+ identity: None,
+ }
+ }
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RealityConfig {
+ pub client_fingerprint: Option,
+ pub support_x25519mlkem768: bool,
pub server_name: String,
pub public_key: [u8; 32],
pub short_id: Vec,
+ pub alpn: Vec>,
+}
+
+impl RealityConfig {
+ pub(crate) fn validate_fingerprint(&self) -> Result<()> {
+ if self.support_x25519mlkem768
+ && !matches!(
+ self.client_fingerprint,
+ None | Some(ClientFingerprint::Chrome133)
+ )
+ {
+ return invalid(
+ "hybrid REALITY requires client-fingerprint chrome or no named fingerprint",
+ );
+ }
+ Ok(())
+ }
}
#[derive(Debug, Clone, PartialEq, Eq)]
@@ -398,6 +586,10 @@ pub struct XHttpConfig {
pub path: String,
pub host: String,
pub mode: XHttpMode,
+ pub http_version: XHttpVersion,
+ pub headers: XHttpHeaders,
+ pub request: std::sync::Arc,
+ pub reuse: Option>,
pub download: Option>,
}
@@ -406,8 +598,12 @@ pub struct XHttpDownloadConfig {
pub address: String,
pub port: u16,
pub security: SecurityConfig,
+ pub http_version: XHttpVersion,
pub path: String,
pub host: String,
+ pub headers: XHttpHeaders,
+ pub request: std::sync::Arc,
+ pub reuse: Option>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -667,6 +863,12 @@ where
// protocol fields inline avoids extra heap allocations in the startup path.
#[allow(clippy::large_enum_variant)]
enum RawOutbound {
+ #[serde(rename = "hysteria2")]
+ Hysteria2(hysteria2::RawHysteria2),
+ #[serde(rename = "vmess")]
+ Vmess(vmess::RawVmess),
+ #[serde(rename = "trojan")]
+ Trojan(trojan::RawTrojan),
#[serde(rename = "ss")]
Shadowsocks {
name: String,
@@ -684,42 +886,7 @@ enum RawOutbound {
dialer_proxy: Option,
},
#[serde(rename = "vless")]
- Vless {
- name: String,
- server: String,
- port: u16,
- uuid: String,
- #[serde(default)]
- udp: bool,
- tls: bool,
- network: String,
- #[serde(default)]
- encryption: String,
- #[serde(default)]
- flow: String,
- #[serde(default, deserialize_with = "deserialize_present_option")]
- servername: Option,
- #[serde(default, deserialize_with = "deserialize_present_option")]
- alpn: Option>,
- #[serde(
- rename = "dialer-proxy",
- default,
- deserialize_with = "deserialize_present_option"
- )]
- dialer_proxy: Option,
- #[serde(
- rename = "reality-opts",
- default,
- deserialize_with = "deserialize_present_option"
- )]
- reality_opts: Option,
- #[serde(
- rename = "xhttp-opts",
- default,
- deserialize_with = "deserialize_present_option"
- )]
- xhttp_opts: Option,
- },
+ Vless(vless::RawVless),
#[serde(rename = "socks5")]
Socks5 {
name: String,
@@ -756,6 +923,12 @@ enum RawOutbound {
skip_cert_verify: bool,
#[serde(default, deserialize_with = "deserialize_present_option")]
fingerprint: Option,
+ #[serde(
+ rename = "client-fingerprint",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ client_fingerprint: Option,
#[serde(
rename = "dialer-proxy",
default,
@@ -768,16 +941,130 @@ enum RawOutbound {
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct RawXHttpSettings {
+ #[serde(
+ rename = "reuse-settings",
+ default,
+ deserialize_with = "deserialize_present_map"
+ )]
+ reuse_settings: Option,
#[serde(default, deserialize_with = "deserialize_present_option")]
host: Option,
#[serde(default = "default_path")]
path: String,
#[serde(default = "default_xhttp_mode")]
mode: String,
+ #[serde(default)]
+ headers: std::collections::BTreeMap,
+ #[serde(rename = "no-grpc-header", default)]
+ no_grpc_header: bool,
+ #[serde(
+ rename = "x-padding-bytes",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ x_padding_bytes: Option,
+ #[serde(rename = "x-padding-obfs-mode", default)]
+ x_padding_obfs_mode: bool,
+ #[serde(
+ rename = "x-padding-key",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ x_padding_key: Option,
+ #[serde(
+ rename = "x-padding-header",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ x_padding_header: Option,
+ #[serde(
+ rename = "x-padding-placement",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ x_padding_placement: Option,
+ #[serde(
+ rename = "x-padding-method",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ x_padding_method: Option,
+ #[serde(
+ rename = "uplink-http-method",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ uplink_http_method: Option,
+ #[serde(
+ rename = "session-placement",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ session_placement: Option,
+ #[serde(
+ rename = "session-key",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ session_key: Option,
+ #[serde(
+ rename = "session-table",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ session_table: Option,
+ #[serde(
+ rename = "session-length",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ session_length: Option,
+ #[serde(
+ rename = "seq-placement",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ seq_placement: Option,
+ #[serde(
+ rename = "seq-key",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ seq_key: Option,
+ #[serde(
+ rename = "uplink-data-placement",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ uplink_data_placement: Option,
+ #[serde(
+ rename = "uplink-data-key",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ uplink_data_key: Option,
+ #[serde(
+ rename = "uplink-chunk-size",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ uplink_chunk_size: Option,
+ #[serde(
+ rename = "sc-max-each-post-bytes",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ sc_max_each_post_bytes: Option,
+ #[serde(
+ rename = "sc-min-posts-interval-ms",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ sc_min_posts_interval_ms: Option,
#[serde(
rename = "download-settings",
default,
- deserialize_with = "deserialize_present_option"
+ deserialize_with = "deserialize_present_map"
)]
download_settings: Option,
}
@@ -785,9 +1072,30 @@ struct RawXHttpSettings {
impl Default for RawXHttpSettings {
fn default() -> Self {
Self {
+ reuse_settings: None,
host: None,
path: default_path(),
mode: default_xhttp_mode(),
+ headers: Default::default(),
+ no_grpc_header: false,
+ x_padding_bytes: None,
+ x_padding_obfs_mode: false,
+ x_padding_key: None,
+ x_padding_header: None,
+ x_padding_placement: None,
+ x_padding_method: None,
+ uplink_http_method: None,
+ session_placement: None,
+ session_key: None,
+ session_table: None,
+ session_length: None,
+ seq_placement: None,
+ seq_key: None,
+ uplink_data_placement: None,
+ uplink_data_key: None,
+ uplink_chunk_size: None,
+ sc_max_each_post_bytes: None,
+ sc_min_posts_interval_ms: None,
download_settings: None,
}
}
@@ -796,6 +1104,18 @@ impl Default for RawXHttpSettings {
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct RawXHttpDownloadSettings {
+ #[serde(
+ rename = "client-fingerprint",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ client_fingerprint: Option,
+ #[serde(
+ rename = "reuse-settings",
+ default,
+ deserialize_with = "deserialize_present_map"
+ )]
+ reuse_settings: Option,
#[serde(default, deserialize_with = "deserialize_present_option")]
server: Option,
#[serde(default, deserialize_with = "deserialize_present_option")]
@@ -807,15 +1127,66 @@ struct RawXHttpDownloadSettings {
#[serde(default, deserialize_with = "deserialize_present_option")]
alpn: Option>,
#[serde(
- rename = "reality-opts",
+ rename = "skip-cert-verify",
default,
deserialize_with = "deserialize_present_option"
)]
- reality_opts: Option,
+ skip_cert_verify: Option,
+ #[serde(
+ rename = "name-cert-verify",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ name_cert_verify: Option,
+ #[serde(default, deserialize_with = "deserialize_present_option")]
+ fingerprint: Option,
+ #[serde(default, deserialize_with = "deserialize_present_option")]
+ certificate: Option,
+ #[serde(
+ rename = "private-key",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ private_key: Option,
+ #[serde(
+ rename = "reality-opts",
+ default,
+ deserialize_with = "deserialize_present_map"
+ )]
+ reality_opts: Option,
+ #[serde(rename = "jls-opts", default, deserialize_with = "jls::deserialize")]
+ jls_opts: Option,
+ #[serde(rename = "ech-opts", default, deserialize_with = "ech::deserialize")]
+ ech_opts: Option,
#[serde(default, deserialize_with = "deserialize_present_option")]
path: Option,
#[serde(default, deserialize_with = "deserialize_present_option")]
host: Option,
+ #[serde(default, deserialize_with = "deserialize_present_option")]
+ headers: Option>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct RawXHttpDownloadReality {
+ #[serde(
+ rename = "public-key",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ public_key: Option,
+ #[serde(
+ rename = "short-id",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ short_id: Option,
+ #[serde(
+ rename = "support-x25519mlkem768",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ support_x25519mlkem768: Option,
}
#[derive(Debug, Deserialize)]
@@ -825,6 +1196,8 @@ struct RawRealitySettings {
public_key: String,
#[serde(rename = "short-id", default)]
short_id: String,
+ #[serde(rename = "support-x25519mlkem768", default)]
+ support_x25519mlkem768: bool,
}
#[derive(Debug)]
@@ -861,6 +1234,30 @@ where
T::deserialize(deserializer).map(Some)
}
+// Derived structs also accept positional sequences. Configuration objects must
+// remain named maps: in particular, [] must not silently select all defaults.
+fn deserialize_present_map<'de, D, T>(deserializer: D) -> std::result::Result, D::Error>
+where
+ D: Deserializer<'de>,
+ T: Deserialize<'de>,
+{
+ struct NamedMap(std::marker::PhantomData);
+ impl<'de, T: Deserialize<'de>> Visitor<'de> for NamedMap {
+ type Value = T;
+
+ fn expecting(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+ f.write_str("a named configuration map")
+ }
+
+ fn visit_map>(self, map: A) -> std::result::Result {
+ T::deserialize(serde::de::value::MapAccessDeserializer::new(map))
+ }
+ }
+ deserializer
+ .deserialize_map(NamedMap(std::marker::PhantomData))
+ .map(Some)
+}
+
fn deserialize_non_null_vec<'de, D, T>(deserializer: D) -> std::result::Result, D::Error>
where
D: Deserializer<'de>,
@@ -1538,6 +1935,9 @@ pub(crate) fn proxy_graph_order(
impl RawOutbound {
fn normalize(self) -> Result {
let (tag, dialer_proxy, udp, protocol) = match self {
+ Self::Hysteria2(raw) => raw.normalize()?,
+ Self::Vmess(raw) => raw.normalize()?,
+ Self::Trojan(raw) => raw.normalize()?,
Self::Shadowsocks {
name,
server,
@@ -1552,39 +1952,7 @@ impl RawOutbound {
udp,
ProxyProtocol::Shadowsocks(shadowsocks::normalize(server, port, cipher, password)?),
),
- Self::Vless {
- name,
- server,
- port,
- uuid,
- udp,
- tls,
- network,
- encryption,
- flow,
- servername,
- alpn,
- dialer_proxy,
- reality_opts,
- xhttp_opts,
- } => (
- name,
- dialer_proxy,
- udp,
- ProxyProtocol::Vless(normalize_vless(
- server,
- port,
- uuid,
- tls,
- network,
- encryption,
- flow,
- servername,
- alpn,
- reality_opts,
- xhttp_opts,
- )?),
- ),
+ Self::Vless(raw) => raw.normalize()?,
Self::Socks5 {
name,
server,
@@ -1610,12 +1978,10 @@ impl RawOutbound {
alpn,
skip_cert_verify,
fingerprint,
+ client_fingerprint,
dialer_proxy,
- } => (
- name,
- dialer_proxy,
- udp,
- ProxyProtocol::AnyTls(normalize_anytls(
+ } => {
+ let mut config = normalize_anytls(
server,
port,
password,
@@ -1623,8 +1989,11 @@ impl RawOutbound {
alpn,
skip_cert_verify,
fingerprint,
- )?),
- ),
+ )?;
+ config.tls.client_fingerprint =
+ parse_client_fingerprint(client_fingerprint.as_deref())?;
+ (name, dialer_proxy, udp, ProxyProtocol::AnyTls(config))
+ }
};
validate_route_target_definition_name(&tag, "proxy name")?;
if let Some(dialer_proxy) = &dialer_proxy {
@@ -1639,65 +2008,6 @@ impl RawOutbound {
}
}
-#[allow(clippy::too_many_arguments)]
-fn normalize_vless(
- server: String,
- port: u16,
- uuid: String,
- tls: bool,
- network: String,
- encryption: String,
- flow: String,
- servername: Option,
- alpn: Option>,
- reality_opts: Option,
- xhttp_opts: Option,
-) -> Result {
- validate_host(&server, "VLESS server")?;
- validate_port(port, "VLESS")?;
- let id = parse_standard_uuid(&uuid)?;
- if !matches!(encryption.as_str(), "" | "none") {
- return invalid("VLESS encryption must be empty or `none`");
- }
- if !flow.is_empty() {
- return invalid("VLESS flow must be empty");
- }
- if !tls {
- return invalid("VLESS tls must be true");
- }
- if network != "xhttp" {
- return invalid("VLESS network must be `xhttp`");
- }
- if let Some(alpn) = alpn
- && alpn.as_slice() != ["h2"]
- {
- return invalid("VLESS alpn must be [h2] when configured");
- }
- let server_name_is_explicit = servername.is_some();
- let server_name = servername.unwrap_or_else(|| server.clone());
- validate_host(&server_name, "VLESS servername")?;
- let security = match reality_opts {
- Some(reality) => SecurityConfig::Reality(reality.normalize(server_name)?),
- None => SecurityConfig::Tls(TlsConfig { server_name }),
- };
- let xhttp = xhttp_opts.unwrap_or_default().normalize(
- &server,
- port,
- server_name_is_explicit.then_some(security.server_name()),
- security.server_name(),
- &security,
- )?;
- Ok(VlessOutboundConfig {
- address: server,
- port,
- id,
- encryption: VlessEncryption::None,
- flow,
- security,
- xhttp,
- })
-}
-
impl RawRealitySettings {
fn normalize(self, server_name: String) -> Result {
let decoded = URL_SAFE_NO_PAD
@@ -1722,9 +2032,12 @@ impl RawRealitySettings {
}
Ok(RealityConfig {
+ client_fingerprint: None,
+ support_x25519mlkem768: self.support_x25519mlkem768,
server_name,
public_key,
short_id,
+ alpn: vec![b"h2".to_vec()],
})
}
}
@@ -1817,6 +2130,7 @@ fn normalize_anytls(
password,
server_name,
tls: AnyTlsCertificatePolicy {
+ client_fingerprint: None,
alpn,
skip_cert_verify,
fingerprint,
@@ -1832,13 +2146,39 @@ impl RawXHttpSettings {
default_explicit_server_name: Option<&str>,
default_host: &str,
security: &SecurityConfig,
+ http_version: XHttpVersion,
) -> Result {
+ if http_version == XHttpVersion::Http3 && !matches!(security, SecurityConfig::Tls(_)) {
+ return invalid("XHTTP HTTP/3 requires standard TLS");
+ }
+ let headers = XHttpHeaders::normalize(self.headers.clone())?;
+ let has_download = self.download_settings.is_some();
+ let mode = match self.mode.as_str() {
+ "auto" if matches!(security, SecurityConfig::Reality(_)) && has_download => {
+ XHttpMode::StreamUp
+ }
+ "auto" if matches!(security, SecurityConfig::Reality(_)) => XHttpMode::StreamOne,
+ "auto" | "packet-up" => XHttpMode::PacketUp,
+ "stream-one" if !has_download => XHttpMode::StreamOne,
+ "stream-one" => {
+ return invalid("xhttp mode `stream-one` cannot be used with download-settings");
+ }
+ "stream-up" => XHttpMode::StreamUp,
+ _ => return invalid("XHTTP mode must be auto, packet-up, stream-up, or stream-one"),
+ };
+ let request = std::sync::Arc::new(XHttpRequestOptions::normalize(&self, &headers, mode)?);
+ let reuse = self
+ .reuse_settings
+ .map(|raw| raw.normalize(http_version))
+ .transpose()?
+ .map(std::sync::Arc::new);
let Self {
host,
path,
- mode,
download_settings,
+ ..
} = self;
+ let host = host.filter(|value| !value.is_empty());
if path.is_empty()
|| path.len() > 2_048
|| !path.starts_with('/')
@@ -1848,16 +2188,19 @@ impl RawXHttpSettings {
"xhttp-opts.path must be a valid path/query starting with `/` and at most 2048 bytes",
);
}
- let download = download_settings
+ let mut download = download_settings
.map(|settings| {
- settings.normalize(
- default_address,
- default_port,
- default_explicit_server_name,
+ settings.normalize(XHttpDownloadDefaults {
+ address: default_address,
+ port: default_port,
+ explicit_server_name: default_explicit_server_name,
security,
- &path,
- host.as_deref(),
- )
+ http_version,
+ path: &path,
+ explicit_host: host.as_deref(),
+ headers: &headers,
+ reuse: &reuse,
+ })
})
.transpose()?
.map(Box::new);
@@ -1867,60 +2210,106 @@ impl RawXHttpSettings {
|address| format!("[{address}]"),
)
});
- if host.is_empty() || host.len() > 253 || host.parse::().is_err() {
+ if host.is_empty()
+ || host.len() > 253
+ || host.contains('@')
+ || host.parse::().is_err()
+ {
return invalid("xhttp-opts.host must be a valid HTTP authority");
}
- let mode = match mode.as_str() {
- "auto" if matches!(security, SecurityConfig::Reality(_)) && download.is_some() => {
- XHttpMode::StreamUp
- }
- "auto" if matches!(security, SecurityConfig::Reality(_)) => XHttpMode::StreamOne,
- "auto" | "packet-up" => XHttpMode::PacketUp,
- "stream-one" if download.is_none() => XHttpMode::StreamOne,
- "stream-one" => {
- return invalid("xhttp mode `stream-one` cannot be used with download-settings");
- }
- "stream-up" => XHttpMode::StreamUp,
- _ => return invalid("XHTTP mode must be auto, packet-up, stream-up, or stream-one"),
- };
+ if let Some(download) = &mut download {
+ request.validate_headers(&download.headers, &download.path)?;
+ download.request = request.clone();
+ }
Ok(XHttpConfig {
path,
host,
mode,
+ http_version,
+ headers,
+ request,
download,
+ reuse,
})
}
}
+struct XHttpDownloadDefaults<'a> {
+ reuse: &'a Option>,
+ address: &'a str,
+ port: u16,
+ explicit_server_name: Option<&'a str>,
+ security: &'a SecurityConfig,
+ http_version: XHttpVersion,
+ path: &'a str,
+ explicit_host: Option<&'a str>,
+ headers: &'a XHttpHeaders,
+}
+
impl RawXHttpDownloadSettings {
- fn normalize(
- self,
- default_address: &str,
- default_port: u16,
- default_explicit_server_name: Option<&str>,
- default_security: &SecurityConfig,
- default_path: &str,
- default_explicit_host: Option<&str>,
- ) -> Result {
+ fn normalize(self, defaults: XHttpDownloadDefaults<'_>) -> Result {
+ let XHttpDownloadDefaults {
+ reuse: default_reuse,
+ address: default_address,
+ port: default_port,
+ explicit_server_name: default_explicit_server_name,
+ security: default_security,
+ http_version: default_http_version,
+ path: default_path,
+ explicit_host: default_explicit_host,
+ headers: default_headers,
+ } = defaults;
let Self {
server,
port,
tls,
servername,
alpn,
+ skip_cert_verify,
+ name_cert_verify,
+ fingerprint,
+ client_fingerprint,
+ certificate,
+ private_key,
reality_opts,
+ jls_opts,
+ ech_opts,
path,
host,
+ headers,
+ reuse_settings,
} = self;
+ let headers = headers
+ .map(XHttpHeaders::normalize)
+ .transpose()?
+ .unwrap_or_else(|| default_headers.clone());
- if tls == Some(false) {
- return invalid("xhttp-opts.download-settings.tls must be true when configured");
+ let http_version = alpn
+ .as_deref()
+ .map(XHttpVersion::from_alpn)
+ .transpose()?
+ .unwrap_or(default_http_version);
+ let tls = tls.unwrap_or(!matches!(default_security, SecurityConfig::None));
+ let client_fingerprint = match client_fingerprint {
+ Some(value) => parse_client_fingerprint(Some(&value))?,
+ None => default_security.client_fingerprint(),
+ };
+ if client_fingerprint.is_some() && (!tls || http_version == XHttpVersion::Http3) {
+ return invalid(
+ "XHTTP download client-fingerprint requires TCP TLS; clear the inherited profile before selecting plaintext or HTTP/3",
+ );
}
- if let Some(alpn) = &alpn
- && alpn.as_slice() != ["h2"]
+ let reuse = match reuse_settings {
+ Some(raw) => Some(std::sync::Arc::new(raw.normalize(http_version)?)),
+ None => default_reuse.clone(),
+ };
+ if http_version == XHttpVersion::Http1
+ && reuse
+ .as_ref()
+ .is_some_and(|value| value.keep_alive_seconds != 0)
{
- return invalid("xhttp-opts.download-settings.alpn must be [h2] when configured");
+ return invalid("XHTTP HTTP/1 download cannot inherit a keepalive period override");
}
let address = server.unwrap_or_else(|| default_address.to_owned());
@@ -1934,25 +2323,150 @@ impl RawXHttpDownloadSettings {
validate_host(&server_name, "XHTTP download servername")?;
let host = host
.or_else(|| default_explicit_host.map(str::to_owned))
+ .filter(|value| !value.is_empty())
.unwrap_or_else(|| {
server_name
.parse::()
.map_or_else(|_| server_name.clone(), |address| format!("[{address}]"))
});
- if host.is_empty() || host.len() > 253 || host.parse::().is_err() {
+ if host.is_empty()
+ || host.len() > 253
+ || host.contains('@')
+ || host.parse::().is_err()
+ {
return invalid("xhttp-opts.download-settings.host must be a valid HTTP authority");
}
- let security = match reality_opts {
- Some(reality) => SecurityConfig::Reality(reality.normalize(server_name)?),
- None => {
- let mut security = default_security.clone();
- match &mut security {
- SecurityConfig::Tls(config) => config.server_name = server_name,
- SecurityConfig::Reality(config) => config.server_name = server_name,
+ let reality = match reality_opts {
+ None => match default_security {
+ SecurityConfig::Reality(config) => {
+ let mut config = config.clone();
+ config.server_name = server_name.clone();
+ Some(config)
}
- security
- }
+ _ => None,
+ },
+ Some(RawXHttpDownloadReality {
+ public_key: None,
+ short_id: None,
+ support_x25519mlkem768: None,
+ }) => None,
+ Some(RawXHttpDownloadReality {
+ public_key: Some(public_key),
+ short_id,
+ support_x25519mlkem768,
+ }) => Some(
+ RawRealitySettings {
+ public_key,
+ short_id: short_id.unwrap_or_default(),
+ support_x25519mlkem768: support_x25519mlkem768.unwrap_or(false),
+ }
+ .normalize(server_name.clone())?,
+ ),
+ Some(_) => return invalid("XHTTP download REALITY replacement requires public-key"),
};
+ // Resolve inherited leaf policies before choosing the final security
+ // mode. A mode switch must not silently erase a pin or client identity.
+ let mut config = match default_security {
+ SecurityConfig::Tls(config) => config.clone(),
+ SecurityConfig::Jls(config) => config.tls.clone(),
+ _ => TlsConfig::xhttp(server_name.clone()),
+ };
+ config.server_name = server_name;
+ config.client_fingerprint = client_fingerprint;
+ config.alpn = vec![http_version.alpn().to_vec()];
+ config.required_alpn = Some(http_version.alpn().to_vec());
+ if let Some(raw) = ech_opts {
+ config.ech = raw.normalize()?;
+ }
+ if config.ech.is_some() && config.server_name.parse::().is_ok() {
+ return invalid("XHTTP download ECH requires a DNS servername");
+ }
+ if let Some(skip) = skip_cert_verify {
+ config.certificate.skip_cert_verify = skip;
+ }
+ if let Some(name) = name_cert_verify {
+ config.certificate.verification_name = if name.is_empty() {
+ None
+ } else {
+ validate_host(&name, "XHTTP download certificate verification name")?;
+ Some(name)
+ };
+ }
+ if let Some(pin) = fingerprint {
+ config.certificate.fingerprint = if pin.is_empty() {
+ None
+ } else {
+ Some(vless::parse_pin(&pin)?)
+ };
+ }
+ match (certificate, private_key) {
+ (None, None) => {}
+ (Some(certificate), Some(private_key))
+ if certificate.is_empty() && private_key.is_empty() =>
+ {
+ config.identity = None
+ }
+ (Some(certificate), Some(private_key)) => {
+ vless::validate_client_identity(&certificate, &private_key)?;
+ config.identity = Some(TlsIdentityPem {
+ certificate,
+ private_key,
+ });
+ }
+ _ => {
+ return invalid(
+ "XHTTP download certificate and private-key must be replaced or cleared together",
+ );
+ }
+ }
+ let certificate_policy = config.certificate.skip_cert_verify
+ || config.certificate.verification_name.is_some()
+ || config.certificate.fingerprint.is_some()
+ || config.identity.is_some();
+ let jls = match jls_opts {
+ Some(raw) if raw.is_empty() => None,
+ Some(raw) => Some(raw.normalize(config.clone())?),
+ None => match default_security {
+ SecurityConfig::Jls(config) => Some(config.clone()),
+ _ => None,
+ },
+ };
+ if reality.is_some() && jls.is_some() {
+ return invalid("XHTTP download JLS and REALITY are mutually exclusive");
+ }
+ if config.ech.is_some() && (reality.is_some() || jls.is_some() || !tls) {
+ return invalid(
+ "XHTTP download ECH requires standard TLS; clear inherited ECH before changing security mode",
+ );
+ }
+ if (reality.is_some() || jls.is_some() || !tls) && certificate_policy {
+ return invalid(
+ "XHTTP download must explicitly clear inherited certificate policy before changing security mode",
+ );
+ }
+ let security = if let Some(mut reality) = reality {
+ if !tls {
+ return invalid("XHTTP download REALITY requires TLS");
+ }
+ reality.alpn = vec![http_version.alpn().to_vec()];
+ reality.client_fingerprint = client_fingerprint;
+ reality.validate_fingerprint()?;
+ SecurityConfig::Reality(reality)
+ } else if let Some(mut jls) = jls {
+ if !tls {
+ return invalid("XHTTP download JLS requires TLS");
+ }
+ jls.tls = config;
+ jls.validate()?;
+ SecurityConfig::Jls(jls)
+ } else if tls {
+ SecurityConfig::Tls(config)
+ } else {
+ SecurityConfig::None
+ };
+ if http_version == XHttpVersion::Http3 && !matches!(security, SecurityConfig::Tls(_)) {
+ return invalid("XHTTP HTTP/3 download requires standard TLS");
+ }
let path = path.unwrap_or_else(|| default_path.to_owned());
if path.is_empty()
@@ -1968,8 +2482,12 @@ impl RawXHttpDownloadSettings {
address,
port,
security,
+ http_version,
path,
host,
+ headers,
+ request: Default::default(),
+ reuse,
})
}
}
@@ -2796,9 +3314,7 @@ proxies:
fn first_xhttp_download(config: &Config) -> &XHttpDownloadConfig {
first_vless(config)
- .xhttp
- .download
- .as_deref()
+ .download()
.expect("expected XHTTP download settings")
}
@@ -2848,10 +3364,13 @@ proxies:
assert_eq!(first_vless(&config).address, "203.0.113.1");
assert!(matches!(
&first_vless(&config).security,
- SecurityConfig::Tls(TlsConfig { server_name }) if server_name == "example.com"
+ SecurityConfig::Tls(TlsConfig { server_name, .. }) if server_name == "example.com"
));
- assert_eq!(first_vless(&config).xhttp.mode, XHttpMode::PacketUp);
- assert!(first_vless(&config).xhttp.download.is_none());
+ assert_eq!(
+ first_vless(&config).xhttp().unwrap().mode,
+ XHttpMode::PacketUp
+ );
+ assert!(first_vless(&config).xhttp().unwrap().download.is_none());
}
#[test]
@@ -3031,9 +3550,12 @@ geo-update-interval: 24"#,
);
let config = Config::parse_yaml(yaml.as_bytes()).unwrap();
assert_eq!(first_vless(&config).flow, "");
- assert_eq!(first_vless(&config).xhttp.path, "/");
- assert_eq!(first_vless(&config).xhttp.host, "example.com");
- assert_eq!(first_vless(&config).xhttp.mode, XHttpMode::PacketUp);
+ assert_eq!(first_vless(&config).xhttp().unwrap().path, "/");
+ assert_eq!(first_vless(&config).xhttp().unwrap().host, "example.com");
+ assert_eq!(
+ first_vless(&config).xhttp().unwrap().mode,
+ XHttpMode::PacketUp
+ );
assert!(matches!(
config.inbounds[1],
InboundConfig::Tun(TunInboundConfig { mtu: 1_500, .. })
@@ -3195,7 +3717,7 @@ geo-update-interval: 24"#,
.replace("servername: example.com", "servername: '::1'")
.replace(" host: example.com\n", "");
let config = Config::parse_yaml(yaml.as_bytes()).unwrap();
- assert_eq!(first_vless(&config).xhttp.host, "[::1]");
+ assert_eq!(first_vless(&config).xhttp().unwrap().host, "[::1]");
}
#[test]
@@ -3207,19 +3729,25 @@ geo-update-interval: 24"#,
assert_eq!(reality.server_name, "example.com");
assert_eq!(reality.public_key, [7_u8; 32]);
assert_eq!(reality.short_id, [1, 0xa2]);
- assert_eq!(first_vless(&config).xhttp.mode, XHttpMode::StreamOne);
+ assert_eq!(
+ first_vless(&config).xhttp().unwrap().mode,
+ XHttpMode::StreamOne
+ );
}
#[test]
fn auto_mode_tracks_the_security_transport() {
let tls = Config::parse_yaml(CURRENT_TLS.as_bytes()).unwrap();
- assert_eq!(first_vless(&tls).xhttp.mode, XHttpMode::PacketUp);
+ assert_eq!(first_vless(&tls).xhttp().unwrap().mode, XHttpMode::PacketUp);
let reality = Config::parse_yaml(reality_yaml().as_bytes()).unwrap();
- assert_eq!(first_vless(&reality).xhttp.mode, XHttpMode::StreamOne);
+ assert_eq!(
+ first_vless(&reality).xhttp().unwrap().mode,
+ XHttpMode::StreamOne
+ );
let reality_with_download = with_xhttp_download(&reality_yaml(), "");
let reality_with_download = Config::parse_yaml(reality_with_download.as_bytes()).unwrap();
assert_eq!(
- first_vless(&reality_with_download).xhttp.mode,
+ first_vless(&reality_with_download).xhttp().unwrap().mode,
XHttpMode::StreamUp
);
}
@@ -3228,13 +3756,22 @@ geo-update-interval: 24"#,
fn accepts_explicit_supported_xhttp_modes() {
let packet_up = CURRENT_TLS.replace("mode: auto", "mode: packet-up");
let packet_up = Config::parse_yaml(packet_up.as_bytes()).unwrap();
- assert_eq!(first_vless(&packet_up).xhttp.mode, XHttpMode::PacketUp);
+ assert_eq!(
+ first_vless(&packet_up).xhttp().unwrap().mode,
+ XHttpMode::PacketUp
+ );
let stream_one = CURRENT_TLS.replace("mode: auto", "mode: stream-one");
let stream_one = Config::parse_yaml(stream_one.as_bytes()).unwrap();
- assert_eq!(first_vless(&stream_one).xhttp.mode, XHttpMode::StreamOne);
+ assert_eq!(
+ first_vless(&stream_one).xhttp().unwrap().mode,
+ XHttpMode::StreamOne
+ );
let stream_up = CURRENT_TLS.replace("mode: auto", "mode: stream-up");
let stream_up = Config::parse_yaml(stream_up.as_bytes()).unwrap();
- assert_eq!(first_vless(&stream_up).xhttp.mode, XHttpMode::StreamUp);
+ assert_eq!(
+ first_vless(&stream_up).xhttp().unwrap().mode,
+ XHttpMode::StreamUp
+ );
for (mode, expected) in [
("packet-up", XHttpMode::PacketUp),
@@ -3243,7 +3780,7 @@ geo-update-interval: 24"#,
let yaml = with_xhttp_download(CURRENT_TLS, "")
.replace("mode: auto", &format!("mode: {mode}"));
let config = Config::parse_yaml(yaml.as_bytes()).unwrap();
- assert_eq!(first_vless(&config).xhttp.mode, expected);
+ assert_eq!(first_vless(&config).xhttp().unwrap().mode, expected);
}
}
@@ -3258,9 +3795,12 @@ geo-update-interval: 24"#,
assert_eq!(download.host, "example.com");
assert!(matches!(
&download.security,
- SecurityConfig::Tls(TlsConfig { server_name }) if server_name == "example.com"
+ SecurityConfig::Tls(TlsConfig { server_name, .. }) if server_name == "example.com"
));
- assert_eq!(first_vless(&tls_inherited).xhttp.mode, XHttpMode::PacketUp);
+ assert_eq!(
+ first_vless(&tls_inherited).xhttp().unwrap().mode,
+ XHttpMode::PacketUp
+ );
let download_reality_key = URL_SAFE_NO_PAD.encode([9_u8; 32]);
let tls_to_reality = with_xhttp_download(
@@ -3288,7 +3828,10 @@ geo-update-interval: 24"#,
assert_eq!(download_reality.server_name, "reality-download.example.com");
assert_eq!(download_reality.public_key, [9_u8; 32]);
assert_eq!(download_reality.short_id, [2, 0xa3]);
- assert_eq!(first_vless(&tls_to_reality).xhttp.mode, XHttpMode::PacketUp);
+ assert_eq!(
+ first_vless(&tls_to_reality).xhttp().unwrap().mode,
+ XHttpMode::PacketUp
+ );
let reality_inherited = with_xhttp_download(&reality_yaml(), "");
let reality_inherited = Config::parse_yaml(reality_inherited.as_bytes()).unwrap();
@@ -3297,7 +3840,7 @@ geo-update-interval: 24"#,
&first_vless(&reality_inherited).security
);
assert_eq!(
- first_vless(&reality_inherited).xhttp.mode,
+ first_vless(&reality_inherited).xhttp().unwrap().mode,
XHttpMode::StreamUp
);
@@ -3314,7 +3857,10 @@ geo-update-interval: 24"#,
};
assert_eq!(download_reality.server_name, "tls-download.example.com");
assert_eq!(
- first_vless(&reality_with_explicit_tls).xhttp.mode,
+ first_vless(&reality_with_explicit_tls)
+ .xhttp()
+ .unwrap()
+ .mode,
XHttpMode::StreamUp
);
}
@@ -3394,9 +3940,9 @@ geo-update-interval: 24"#,
}
for fields in [
- "tls: false",
- "alpn: []",
- "alpn: [h3]",
+ "tls: 'false'",
+ "alpn: [unknown]",
+ "alpn: [h3, h2]",
"server: 'bad host'",
"port: 0",
"servername: 'bad host'",
@@ -3413,16 +3959,6 @@ geo-update-interval: 24"#,
for fields in [
"shadow-tls-opts: {}",
"restls-opts: {}",
- "jls-opts: {}",
- "ech-opts: {}",
- "headers: {}",
- "reuse-settings: {}",
- "skip-cert-verify: false",
- "name-cert-verify: example.com",
- "fingerprint: pinned",
- "certificate: cert.pem",
- "private-key: key.pem",
- "client-fingerprint: chrome",
"mode: stream-up",
"typo: true",
] {
@@ -3434,11 +3970,7 @@ geo-update-interval: 24"#,
);
}
- for unsupported in [
- " shadow-tls-opts: {}\n",
- " restls-opts: {}\n",
- " jls-opts: null\n",
- ] {
+ for unsupported in [" shadow-tls-opts: {}\n", " restls-opts: {}\n"] {
let yaml = CURRENT_TLS.replace(
" xhttp-opts:\n",
&format!("{unsupported} xhttp-opts:\n"),
@@ -3478,13 +4010,9 @@ geo-update-interval: 24"#,
CURRENT_TLS.replace(" server: ", " vnext: []\n server: "),
CURRENT_TLS.replace(" network: xhttp", " typo: true\n network: xhttp"),
CURRENT_TLS.replace(" path: /x", " typo: true\n path: /x"),
- CURRENT_TLS.replace(
- " servername: example.com",
- " client-fingerprint: chrome\n servername: example.com",
- ),
reality_yaml().replace(
" public-key:",
- " support-x25519mlkem768: true\n public-key:",
+ " unknown-reality-option: true\n public-key:",
),
] {
let error = Config::parse_yaml(yaml.as_bytes()).unwrap_err();
@@ -3943,7 +4471,6 @@ authentication:
fn rejects_anytls_fields_outside_the_locked_subset() {
for field in [
"tls: true",
- "client-fingerprint: chrome",
"ech-opts: {}",
"certificate: client.crt",
"private-key: client.key",
@@ -4078,10 +4605,10 @@ authentication:
#[test]
fn validates_tls_and_xhttp_whitelists() {
for yaml in [
- CURRENT_TLS.replace("alpn: [h2]", "alpn: [http/1.1]"),
+ CURRENT_TLS.replace("alpn: [h2]", "alpn: [unknown]"),
CURRENT_TLS.replace(
" alpn: [h2]",
- " alpn: [h2]\n skip-cert-verify: false",
+ " alpn: [h2]\n skip-cert-verify: null",
),
CURRENT_TLS.replace(" alpn: [h2]", " alpn: [h2]\n allowInsecure: true"),
CURRENT_TLS.replace("path: /x", "path: '/bad path'"),
diff --git a/src/config/trojan.rs b/src/config/trojan.rs
new file mode 100644
index 0000000..7a16115
--- /dev/null
+++ b/src/config/trojan.rs
@@ -0,0 +1,326 @@
+use serde::Deserialize;
+use std::collections::BTreeMap;
+
+use super::{
+ AnyTlsCertificatePolicy, ProxyProtocol, deserialize_present_option, invalid, validate_host,
+ validate_port,
+};
+use crate::Result;
+
+#[derive(Clone, PartialEq, Eq)]
+pub struct TrojanOutboundConfig {
+ pub address: String,
+ pub port: u16,
+ pub password: String,
+ pub server_name: String,
+ pub tls: AnyTlsCertificatePolicy,
+ pub transport: TrojanTransport,
+}
+
+#[derive(Clone, PartialEq, Eq)]
+pub enum TrojanTransport {
+ Tcp,
+ WebSocket {
+ uri: String,
+ headers: BTreeMap,
+ max_early_data: u16,
+ early_data_header_name: String,
+ },
+ Grpc {
+ uri: String,
+ },
+}
+
+impl std::fmt::Debug for TrojanTransport {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.write_str(match self {
+ Self::Tcp => "Tcp",
+ Self::WebSocket { .. } => "WebSocket",
+ Self::Grpc { .. } => "Grpc",
+ })
+ }
+}
+
+impl TrojanTransport {
+ pub fn required_alpn(&self) -> Option<&'static [u8]> {
+ match self {
+ Self::Tcp => None,
+ Self::WebSocket { .. } => Some(b"http/1.1"),
+ Self::Grpc { .. } => Some(b"h2"),
+ }
+ }
+
+ #[cfg(feature = "stream-transport")]
+ pub fn websocket_options(&self) -> std::io::Result> {
+ let Self::WebSocket {
+ uri,
+ headers,
+ max_early_data,
+ early_data_header_name,
+ } = self
+ else {
+ return Ok(None);
+ };
+ websocket_options(uri, headers, *max_early_data, early_data_header_name).map(Some)
+ }
+}
+
+#[cfg(feature = "stream-transport")]
+pub(super) fn websocket_options(
+ uri: &str,
+ headers: &BTreeMap,
+ max_early_data: u16,
+ early_data_header_name: &str,
+) -> std::io::Result {
+ use crate::transport::{WebSocketEarlyData, WebSocketOptions};
+ let invalid = || {
+ std::io::Error::new(
+ std::io::ErrorKind::InvalidInput,
+ "invalid WebSocket options",
+ )
+ };
+ let mut map = http::HeaderMap::new();
+ for (name, value) in headers {
+ let name = http::HeaderName::from_bytes(name.as_bytes()).map_err(|_| invalid())?;
+ if map
+ .insert(name, value.parse().map_err(|_| invalid())?)
+ .is_some()
+ {
+ return Err(invalid());
+ }
+ }
+ let early = if max_early_data == 0 {
+ None
+ } else if early_data_header_name.is_empty() {
+ Some(WebSocketEarlyData::Path {
+ max_bytes: usize::from(max_early_data),
+ })
+ } else {
+ Some(WebSocketEarlyData::Header {
+ name: early_data_header_name.parse().map_err(|_| invalid())?,
+ max_bytes: usize::from(max_early_data),
+ })
+ };
+ WebSocketOptions::new(uri, map, early)
+}
+#[derive(Default, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct RawWebSocket {
+ #[serde(default, deserialize_with = "deserialize_present_option")]
+ path: Option,
+ #[serde(default)]
+ headers: BTreeMap,
+ #[serde(rename = "max-early-data", default)]
+ max_early_data: u16,
+ #[serde(
+ rename = "early-data-header-name",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ early_data_header_name: Option,
+}
+
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct RawGrpc {
+ #[serde(rename = "grpc-service-name")]
+ service: String,
+}
+
+fn uri(scheme: &str, server: &str, port: u16, path: &str) -> Result {
+ if !path.starts_with('/') || path.contains(['\r', '\n', '#']) {
+ return invalid("invalid Trojan transport path");
+ }
+ let authority = if server.parse::().is_ok() {
+ format!("[{server}]:{port}")
+ } else {
+ format!("{server}:{port}")
+ };
+ let uri = http::Uri::builder()
+ .scheme(scheme)
+ .authority(authority)
+ .path_and_query(path)
+ .build()
+ .map_err(|_| crate::VCoreError::InvalidConfig("invalid Trojan transport URI".into()))?;
+ // Same bounded HTTP head envelope as the shared stream adapters.
+ if uri.to_string().len() > 16 * 1024 - 256 {
+ return invalid("Trojan transport URI exceeds HTTP head limit");
+ }
+ Ok(uri.to_string())
+}
+
+impl std::fmt::Debug for TrojanOutboundConfig {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.debug_struct("TrojanOutboundConfig")
+ .finish_non_exhaustive()
+ }
+}
+
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(super) struct RawTrojan {
+ name: String,
+ server: String,
+ port: u16,
+ password: String,
+ #[serde(default)]
+ udp: bool,
+ #[serde(default, deserialize_with = "deserialize_present_option")]
+ network: Option,
+ #[serde(
+ rename = "ws-opts",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ ws: Option,
+ #[serde(
+ rename = "grpc-opts",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ grpc: Option,
+ #[serde(default, deserialize_with = "deserialize_present_option")]
+ sni: Option,
+ #[serde(default, deserialize_with = "deserialize_present_option")]
+ alpn: Option>,
+ #[serde(rename = "skip-cert-verify", default)]
+ skip_cert_verify: bool,
+ #[serde(default, deserialize_with = "deserialize_present_option")]
+ fingerprint: Option,
+ #[serde(
+ rename = "client-fingerprint",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ client_fingerprint: Option,
+ #[serde(
+ rename = "dialer-proxy",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ dialer_proxy: Option,
+}
+
+impl std::fmt::Debug for RawTrojan {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.debug_struct("RawTrojan").finish_non_exhaustive()
+ }
+}
+
+impl RawTrojan {
+ pub(super) fn normalize(self) -> Result<(String, Option, bool, ProxyProtocol)> {
+ if !cfg!(feature = "outbound-trojan") {
+ return invalid("Trojan outbound support is disabled at build time");
+ }
+ validate_host(&self.server, "Trojan server")?;
+ validate_port(self.port, "Trojan")?;
+ if self.password.is_empty() {
+ return invalid("Trojan password must not be empty");
+ }
+ let transport = match (self.network.as_deref().unwrap_or("tcp"), self.ws, self.grpc) {
+ ("tcp", None, None) => TrojanTransport::Tcp,
+ ("ws", ws, None) => {
+ let ws = ws.unwrap_or_default();
+ if ws.max_early_data > 2048
+ || (ws.max_early_data == 0 && ws.early_data_header_name.is_some())
+ {
+ return invalid("invalid Trojan WebSocket early-data options");
+ }
+ let transport = TrojanTransport::WebSocket {
+ uri: uri(
+ "wss",
+ &self.server,
+ self.port,
+ ws.path.as_deref().unwrap_or("/"),
+ )?,
+ headers: ws.headers,
+ max_early_data: ws.max_early_data,
+ early_data_header_name: ws
+ .early_data_header_name
+ .unwrap_or_else(|| "Sec-WebSocket-Protocol".into()),
+ };
+ #[cfg(feature = "stream-transport")]
+ if transport.websocket_options().is_err() {
+ return invalid("invalid Trojan WebSocket options");
+ }
+ transport
+ }
+ ("grpc", None, Some(grpc)) if !grpc.service.is_empty() => {
+ let path = if grpc.service.starts_with('/') {
+ grpc.service
+ } else {
+ format!("/{}/Tun", grpc.service)
+ };
+ if path.contains('?') {
+ return invalid("invalid Trojan gRPC service path");
+ }
+ TrojanTransport::Grpc {
+ uri: uri("https", &self.server, self.port, &path)?,
+ }
+ }
+ _ => return invalid("Trojan requires tcp, ws with ws-opts, or grpc with grpc-opts"),
+ };
+ let server_name = self.sni.unwrap_or_else(|| self.server.clone());
+ validate_host(&server_name, "Trojan sni")?;
+ let alpn: Vec> = self
+ .alpn
+ .unwrap_or_else(|| {
+ transport
+ .required_alpn()
+ .map(|value| vec![String::from_utf8(value.to_vec()).unwrap()])
+ .unwrap_or_default()
+ })
+ .into_iter()
+ .map(String::into_bytes)
+ .collect();
+ if alpn
+ .iter()
+ .any(|value| value.is_empty() || value.len() > 255)
+ || alpn.iter().map(|value| value.len() + 1).sum::() > 65_533
+ {
+ return invalid("invalid Trojan ALPN list");
+ }
+ if transport
+ .required_alpn()
+ .is_some_and(|required| !alpn.iter().any(|value| value == required))
+ {
+ return invalid("Trojan ALPN does not include the selected transport");
+ }
+ let fingerprint = self
+ .fingerprint
+ .map(|value| {
+ let hex: Vec = value.trim().bytes().filter(|byte| *byte != b':').collect();
+ if hex.len() != 64 || !hex.iter().all(u8::is_ascii_hexdigit) {
+ return invalid("Trojan fingerprint must be a SHA-256 certificate digest");
+ }
+ let mut pin = [0; 32];
+ for (byte, pair) in pin.iter_mut().zip(hex.as_chunks::<2>().0) {
+ *byte = ((pair[0] as char).to_digit(16).unwrap() * 16
+ + (pair[1] as char).to_digit(16).unwrap())
+ as u8;
+ }
+ Ok(pin)
+ })
+ .transpose()?;
+ Ok((
+ self.name,
+ self.dialer_proxy,
+ self.udp,
+ ProxyProtocol::Trojan(TrojanOutboundConfig {
+ address: self.server,
+ port: self.port,
+ password: self.password,
+ server_name,
+ transport,
+ tls: AnyTlsCertificatePolicy {
+ client_fingerprint: super::parse_client_fingerprint(
+ self.client_fingerprint.as_deref(),
+ )?,
+ alpn,
+ skip_cert_verify: self.skip_cert_verify,
+ fingerprint,
+ },
+ }),
+ ))
+ }
+}
diff --git a/src/config/vless.rs b/src/config/vless.rs
new file mode 100644
index 0000000..30796a9
--- /dev/null
+++ b/src/config/vless.rs
@@ -0,0 +1,521 @@
+//! VLESS public normalization. Transport options share the common stream adapters;
+//! security and VLESS-specific behavior remain independent of VMess.
+use super::vmess::{RawGrpc, RawH2, RawHttp, RawWs};
+use super::*;
+
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct VlessStreamOptions {
+ pub http_upgrade: bool,
+ pub fast_open: bool,
+ pub grpc: GrpcOptions,
+ pub sing_mux: Option,
+}
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum SingMuxProtocol {
+ #[default]
+ H2Mux,
+ Smux,
+ Yamux,
+}
+
+#[derive(Clone, Debug, Default, PartialEq, Eq, Deserialize)]
+#[serde(deny_unknown_fields, rename_all = "kebab-case")]
+pub struct SingMuxConfig {
+ #[serde(default)]
+ pub enabled: bool,
+ #[serde(default)]
+ pub protocol: SingMuxProtocol,
+ #[serde(default)]
+ pub max_connections: u32,
+ #[serde(default)]
+ pub min_streams: u32,
+ #[serde(default)]
+ pub max_streams: u32,
+ #[serde(default)]
+ pub padding: bool,
+ #[serde(default)]
+ pub only_tcp: bool,
+}
+#[derive(Clone, PartialEq, Eq)]
+pub struct GrpcOptions {
+ pub user_agent: String,
+ pub ping_interval: u64,
+ pub max_connections: usize,
+ pub min_streams: usize,
+ pub max_streams: usize,
+}
+impl std::fmt::Debug for GrpcOptions {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.debug_struct("GrpcOptions").finish_non_exhaustive()
+ }
+}
+impl Default for GrpcOptions {
+ fn default() -> Self {
+ Self {
+ user_agent: "grpc-go/1.36.0".into(),
+ ping_interval: 0,
+ max_connections: 1,
+ min_streams: 0,
+ max_streams: 0,
+ }
+ }
+}
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct RawVlessWs {
+ #[serde(default, deserialize_with = "deserialize_present_option")]
+ path: Option,
+ #[serde(default)]
+ headers: std::collections::BTreeMap,
+ #[serde(rename = "max-early-data", default)]
+ max_early_data: u16,
+ #[serde(
+ rename = "early-data-header-name",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ early_data_header_name: Option,
+ #[serde(rename = "v2ray-http-upgrade", default)]
+ http_upgrade: bool,
+ #[serde(rename = "v2ray-http-upgrade-fast-open", default)]
+ fast_open: bool,
+}
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct RawVlessGrpc {
+ #[serde(rename = "grpc-service-name")]
+ service: String,
+ #[serde(
+ rename = "grpc-user-agent",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ user_agent: Option,
+ #[serde(rename = "ping-interval", default)]
+ ping_interval: u64,
+ #[serde(rename = "max-connections", default)]
+ max_connections: usize,
+ #[serde(rename = "min-streams", default)]
+ min_streams: usize,
+ #[serde(rename = "max-streams", default)]
+ max_streams: usize,
+}
+
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(super) struct RawVless {
+ name: String,
+ server: String,
+ port: u16,
+ uuid: String,
+ #[serde(default)]
+ udp: bool,
+ #[serde(default)]
+ tls: bool,
+ #[serde(default, deserialize_with = "deserialize_present_option")]
+ network: Option,
+ #[serde(rename = "packet-encoding", default)]
+ packet_encoding: VlessPacketEncoding,
+ #[serde(default)]
+ encryption: String,
+ #[serde(default)]
+ flow: String,
+ #[serde(default, deserialize_with = "deserialize_present_option")]
+ servername: Option,
+ #[serde(default, deserialize_with = "deserialize_present_option")]
+ alpn: Option>,
+ #[serde(
+ rename = "dialer-proxy",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ dialer_proxy: Option,
+ #[serde(
+ rename = "reality-opts",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ reality_opts: Option,
+ #[serde(
+ rename = "jls-opts",
+ default,
+ deserialize_with = "super::jls::deserialize"
+ )]
+ jls_opts: Option,
+ #[serde(
+ rename = "ech-opts",
+ default,
+ deserialize_with = "super::ech::deserialize"
+ )]
+ ech_opts: Option,
+ #[serde(
+ rename = "xhttp-opts",
+ default,
+ deserialize_with = "deserialize_present_map"
+ )]
+ xhttp_opts: Option,
+
+ #[serde(default, deserialize_with = "deserialize_present_map")]
+ smux: Option,
+
+ #[serde(
+ rename = "ws-opts",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ ws: Option,
+ #[serde(
+ rename = "grpc-opts",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ grpc: Option,
+ #[serde(
+ rename = "http-opts",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ http: Option,
+ #[serde(
+ rename = "h2-opts",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ h2: Option,
+ #[serde(
+ rename = "skip-cert-verify",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ skip_cert_verify: Option,
+ #[serde(default, deserialize_with = "deserialize_present_option")]
+ fingerprint: Option,
+ #[serde(
+ rename = "client-fingerprint",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ client_fingerprint: Option,
+ #[serde(
+ rename = "name-cert-verify",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ name_cert_verify: Option,
+ #[serde(default, deserialize_with = "deserialize_present_option")]
+ certificate: Option