perf: tune jemalloc RSS decay for faster memory reclamation (#2428)

The current malloc_conf only sets retain:false, which prevents jemalloc from retaining virtual memory but does not actively purge dirty/muzzy pages. On long-running EasyTier nodes this can lead to inflated RSS because freed arena pages are not returned to the OS promptly.

This tunes the jemalloc decay parameters:

background_thread:true — enables background GC threads so purge happens without blocking allocation hot paths.
dirty_decay_ms:1000 / muzzy_decay_ms:1000 — return unused pages to the OS within ~1s instead of holding them indefinitely.

.github/SECURITY.md

@@ -0,0 +1,28 @@
+# Security Policy
+
+[简体中文](SECURITY.zh-CN.md) | English
+
+## Supported Versions
+
+Security updates are provided for the latest EasyTier release. Before reporting a vulnerability, please verify it against the latest release or the current `main` branch when practical.
+
+| Version | Supported |
+| --- | --- |
+| Latest release | Yes |
+| Older releases | No |
+
+## Reporting a Vulnerability
+
+Please report suspected vulnerabilities through GitHub's [private vulnerability reporting form](https://github.com/EasyTier/EasyTier/security/advisories/new).
+
+Do not disclose the vulnerability in a public issue, discussion, or pull request. A useful report should include:
+
+- the affected EasyTier version or commit;
+- the affected platform and relevant configuration, with secrets removed;
+- a description of the vulnerability and its potential impact;
+- reproducible steps or a minimal proof of concept; and
+- any known mitigations or workarounds.
+
+The maintainers will assess the report and coordinate remediation and disclosure through the private advisory. Please allow reasonable time for a fix before publishing details.
+
+When investigating, avoid accessing or modifying other users' data, disrupting services, or violating applicable laws.

.github/SECURITY.zh-CN.md

@@ -0,0 +1,28 @@
+# 安全策略
+
+简体中文 | [English](SECURITY.md)
+
+## 支持的版本
+
+EasyTier 仅为最新正式版本提供安全更新。报告漏洞前，请尽可能在最新正式版本或当前 `main` 分支上确认问题仍然存在。
+
+| 版本 | 是否支持 |
+| --- | --- |
+| 最新正式版本 | 是 |
+| 更早版本 | 否 |
+
+## 报告安全漏洞
+
+请通过 GitHub 的[私有漏洞报告表单](https://github.com/EasyTier/EasyTier/security/advisories/new)报告疑似安全漏洞。
+
+请勿在公开 Issue、Discussion 或 Pull Request 中披露漏洞。一份有效的报告应包括：
+
+- 受影响的 EasyTier 版本或提交；
+- 受影响的平台和相关配置，请移除其中的密钥等敏感信息；
+- 漏洞说明及其潜在影响；
+- 可复现的步骤或最小概念验证；
+- 已知的缓解措施或临时解决方案。
+
+维护者将评估报告，并通过私有安全公告协调修复和披露。请在公开漏洞详情前为修复预留合理时间。
+
+调查漏洞时，请勿访问或修改其他用户的数据、干扰服务或违反适用的法律法规。

.github/workflows/core.yml

@@ -1,6 +1,7 @@
 name: EasyTier Core
 
 on:
+  workflow_dispatch:
   push:
     branches: [ "develop", "main", "releases/**" ]
   pull_request:
@@ -21,22 +22,45 @@ defaults:
 
 jobs:
   pre_job:
-    # continue-on-error: true # Uncomment once integration is finished
     runs-on: ubuntu-latest
     if: github.event_name != 'pull_request' || !github.event.pull_request.draft
-    # Map a step output to a job output
+    env:
+      RELEVANT_PATHS: >-
+        ["Cargo.toml", "Cargo.lock", "rust-toolchain.toml", ".cargo/**",
+        "pnpm-lock.yaml", "pnpm-workspace.yaml", "package.json", "easytier/**",
+        "easytier-core/**", "easytier-proto/**", "easytier-rpc-build/**",
+        "easytier-web/**", "easytier-contrib/easytier-magisk/**",
+        ".github/workflows/core.yml", ".github/actions/**"]
     outputs:
-      # do not skip push on branch starts with releases/
-      should_skip: ${{ steps.skip_check.outputs.should_skip == 'true' && !startsWith(github.ref_name, 'releases/') }}
+      # Release builds must run even if they only change release metadata.
+      should_skip: >-
+        ${{
+          (
+            steps.skip_check.outputs.should_skip == 'true' ||
+            (
+              github.event_name == 'pull_request' &&
+              steps.path_filter.outputs.relevant != 'true'
+            )
+          ) &&
+          !startsWith(github.ref_name, 'releases/')
+        }}
     steps:
       - id: skip_check
         uses: fkirc/skip-duplicate-actions@v5
         with:
-          # All of these options are optional, so you can remove them if you are happy with the defaults
           concurrent_skipping: 'same_content_newer'
           skip_after_successful_duplicate: 'true'
           cancel_others: 'true'
-          paths: '["Cargo.toml", "Cargo.lock", "easytier/**", "easytier-core/**", "easytier-proto/**", ".github/workflows/core.yml", ".github/actions/**", "easytier-web/**"]'
+          paths: ${{ env.RELEVANT_PATHS }}
+
+      - id: path_filter
+        if: >-
+          github.event_name == 'pull_request' &&
+          steps.skip_check.outputs.should_skip != 'true'
+        uses: dorny/paths-filter@v4
+        with:
+          filters: |
+            relevant: ${{ env.RELEVANT_PATHS }}
   build_web:
     runs-on: ubuntu-latest
     needs: pre_job
@@ -261,6 +285,47 @@ jobs:
           path: |
             ./artifacts/*
 
+      - name: Prepare SignPath test artifact
+        if: ${{ github.event_name == 'workflow_dispatch' && contains(matrix.TARGET, 'windows') }}
+        run: |
+          mkdir -p ./signpath-artifacts
+          cp \
+            ./artifacts/easytier-core.exe \
+            ./artifacts/easytier-cli.exe \
+            ./artifacts/easytier-web.exe \
+            ./artifacts/easytier-web-embed.exe \
+            ./signpath-artifacts/
+
+      - name: Upload unsigned SignPath test artifact
+        if: ${{ github.event_name == 'workflow_dispatch' && contains(matrix.TARGET, 'windows') }}
+        id: signpath-upload
+        uses: actions/upload-artifact@v5
+        with:
+          name: signpath-unsigned-${{ matrix.ARTIFACT_NAME }}
+          path: ./signpath-artifacts/*
+          if-no-files-found: error
+
+      - name: Submit SignPath test-signing request
+        if: ${{ github.event_name == 'workflow_dispatch' && contains(matrix.TARGET, 'windows') }}
+        uses: signpath/github-action-submit-signing-request@v2
+        with:
+          api-token: ${{ secrets.SIGNPATH_API_TOKEN }}
+          organization-id: 368cf38d-86d5-4bfe-a1fa-82a50dce7e9f
+          project-slug: EasyTier
+          signing-policy-slug: test-signing
+          artifact-configuration-slug: initial
+          github-artifact-id: ${{ steps.signpath-upload.outputs.artifact-id }}
+          wait-for-completion: true
+          output-artifact-directory: ./signpath-signed-artifacts
+
+      - name: Upload signed SignPath test artifact
+        if: ${{ github.event_name == 'workflow_dispatch' && contains(matrix.TARGET, 'windows') }}
+        uses: actions/upload-artifact@v5
+        with:
+          name: signpath-signed-${{ matrix.ARTIFACT_NAME }}
+          path: ./signpath-signed-artifacts/*
+          if-no-files-found: error
+
   build_magisk:
     runs-on: ubuntu-latest
     needs: [ pre_job, build_web, build ]
@@ -276,13 +341,22 @@ jobs:
           name: easytier-linux-aarch64
           path: ./downloaded-binaries/  # 独立目录避免冲突
 
-      # 将二进制文件复制到 Magisk 模块目录
-      - name: Prepare binaries
+      - name: Download Magisk WebUI
+        uses: actions/download-artifact@v4
+        with:
+          name: easytier-web-dashboard
+          path: ./downloaded-webui/
+
+      # 将二进制文件和 WebUI 复制到 Magisk 模块目录
+      - name: Prepare Magisk module
         run: |
-          mkdir -p ./easytier-contrib/easytier-magisk/
-          cp ./downloaded-binaries/easytier-core ./easytier-contrib/easytier-magisk/
-          cp ./downloaded-binaries/easytier-cli ./easytier-contrib/easytier-magisk/
-          cp ./downloaded-binaries/easytier-web ./easytier-contrib/easytier-magisk/
+          module_dir=./easytier-contrib/easytier-magisk
+          mkdir -p "$module_dir/webroot"
+          cp ./downloaded-binaries/easytier-core "$module_dir/"
+          cp ./downloaded-binaries/easytier-cli "$module_dir/"
+          cp ./downloaded-binaries/easytier-web "$module_dir/"
+          cp -R ./downloaded-webui/config-generator/. "$module_dir/webroot/"
+          test -f "$module_dir/webroot/index.html"
 
       # 上传生成的模块
       - name: Upload Magisk Module

.github/workflows/docker.yml

@@ -11,7 +11,7 @@ on:
       image_tag:
         description: 'Tag for this image build'
         type: string
-        default: 'v2.6.4'
+        default: 'v2.7.0'
         required: true
       mark_latest:
         description: 'Mark this image as latest'

.github/workflows/go.yml

@@ -0,0 +1,44 @@
+name: EasyTier Go
+
+on:
+  push:
+    branches: ["develop", "main", "releases/**"]
+    paths:
+      - "easytier-go/**"
+      - ".github/workflows/go.yml"
+  pull_request:
+    branches: ["develop", "main"]
+    types: [opened, synchronize, reopened, ready_for_review]
+    paths:
+      - "easytier-go/**"
+      - ".github/workflows/go.yml"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test Go modules
+    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-go@v6
+        with:
+          go-version: "1.25.x"
+          cache-dependency-path: |
+            easytier-go/go.sum
+            easytier-go/examples/tun/go.sum
+
+      - name: Test main module
+        working-directory: easytier-go
+        run: go test ./...
+
+      - name: Test TUN example module
+        working-directory: easytier-go/examples/tun
+        run: go test ./...

.github/workflows/gui.yml

@@ -21,21 +21,47 @@ defaults:
 
 jobs:
   pre_job:
-    # continue-on-error: true # Uncomment once integration is finished
     runs-on: ubuntu-latest
     if: github.event_name != 'pull_request' || !github.event.pull_request.draft
-    # Map a step output to a job output
+    env:
+      RELEVANT_PATHS: >-
+        ["Cargo.toml", "Cargo.lock", "rust-toolchain.toml", ".cargo/**",
+        "pnpm-lock.yaml", "pnpm-workspace.yaml", "package.json", "easytier/**",
+        "easytier-core/**", "easytier-proto/**", "easytier-rpc-build/**",
+        "easytier-gui/**", "tauri-plugin-vpnservice/**",
+        "easytier-web/frontend-lib/**", ".github/workflows/gui.yml",
+        ".github/actions/**"]
     outputs:
-      should_skip: ${{ steps.skip_check.outputs.should_skip == 'true' && !startsWith(github.ref_name, 'releases/') }}
+      # Release builds must run even if they only change release metadata.
+      should_skip: >-
+        ${{
+          (
+            steps.skip_check.outputs.should_skip == 'true' ||
+            (
+              github.event_name == 'pull_request' &&
+              steps.path_filter.outputs.relevant != 'true'
+            )
+          ) &&
+          !startsWith(github.ref_name, 'releases/')
+        }}
     steps:
       - id: skip_check
         uses: fkirc/skip-duplicate-actions@v5
         with:
-          # All of these options are optional, so you can remove them if you are happy with the defaults
           concurrent_skipping: 'same_content_newer'
           skip_after_successful_duplicate: 'true'
           cancel_others: 'true'
-          paths: '["Cargo.toml", "Cargo.lock", "easytier/**", "easytier-core/**", "easytier-gui/**", ".github/workflows/gui.yml", ".github/actions/**", "easytier-web/frontend-lib/**"]'
+          paths: ${{ env.RELEVANT_PATHS }}
+
+      - id: path_filter
+        if: >-
+          github.event_name == 'pull_request' &&
+          steps.skip_check.outputs.should_skip != 'true'
+        uses: dorny/paths-filter@v4
+        with:
+          filters: |
+            relevant: ${{ env.RELEVANT_PATHS }}
+
   build-gui:
     strategy:
       fail-fast: true

.github/workflows/js.yml

@@ -0,0 +1,62 @@
+name: EasyTier JavaScript Hosts
+
+on:
+  push:
+    branches: ["develop", "main", "releases/**"]
+    paths:
+      - "Cargo.toml"
+      - "Cargo.lock"
+      - "easytier-core/**"
+      - "easytier-proto/**"
+      - "easytier-js/**"
+      - ".github/workflows/js.yml"
+  pull_request:
+    branches: ["develop", "main"]
+    types: [opened, synchronize, reopened, ready_for_review]
+    paths:
+      - "Cargo.toml"
+      - "Cargo.lock"
+      - "easytier-core/**"
+      - "easytier-proto/**"
+      - "easytier-js/**"
+      - ".github/workflows/js.yml"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: 1.95
+          target: wasm32-wasip1
+          cache: false
+          rustflags: ''
+
+      - uses: arduino/setup-protoc@v3
+        with:
+          version: '35.1'
+          repo-token: ${{ github.token }}
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 22
+
+      - uses: pnpm/action-setup@v5
+        with:
+          version: 10
+          run_install: false
+
+      - name: Install dependencies
+        run: pnpm --dir easytier-js install --frozen-lockfile
+
+      - name: Build and test
+        run: pnpm --dir easytier-js check

.github/workflows/mobile.yml

@@ -21,21 +21,47 @@ defaults:
 
 jobs:
   pre_job:
-    # continue-on-error: true # Uncomment once integration is finished
     runs-on: ubuntu-latest
     if: github.event_name != 'pull_request' || !github.event.pull_request.draft
-    # Map a step output to a job output
+    env:
+      RELEVANT_PATHS: >-
+        ["Cargo.toml", "Cargo.lock", "rust-toolchain.toml", ".cargo/**",
+        "pnpm-lock.yaml", "pnpm-workspace.yaml", "package.json", "easytier/**",
+        "easytier-core/**", "easytier-proto/**", "easytier-rpc-build/**",
+        "easytier-gui/**", "tauri-plugin-vpnservice/**",
+        "easytier-web/frontend-lib/**", ".github/workflows/mobile.yml",
+        ".github/actions/**"]
     outputs:
-      should_skip: ${{ steps.skip_check.outputs.should_skip == 'true' && !startsWith(github.ref_name, 'releases/') }}
+      # Release builds must run even if they only change release metadata.
+      should_skip: >-
+        ${{
+          (
+            steps.skip_check.outputs.should_skip == 'true' ||
+            (
+              github.event_name == 'pull_request' &&
+              steps.path_filter.outputs.relevant != 'true'
+            )
+          ) &&
+          !startsWith(github.ref_name, 'releases/')
+        }}
     steps:
       - id: skip_check
         uses: fkirc/skip-duplicate-actions@v5
         with:
-          # All of these options are optional, so you can remove them if you are happy with the defaults
           concurrent_skipping: 'same_content_newer'
           skip_after_successful_duplicate: 'true'
           cancel_others: 'true'
-          paths: '["Cargo.toml", "Cargo.lock", "easytier/**", "easytier-core/**", "easytier-gui/**", "tauri-plugin-vpnservice/**", ".github/workflows/mobile.yml", ".github/actions/**"]'
+          paths: ${{ env.RELEVANT_PATHS }}
+
+      - id: path_filter
+        if: >-
+          github.event_name == 'pull_request' &&
+          steps.skip_check.outputs.should_skip != 'true'
+        uses: dorny/paths-filter@v4
+        with:
+          filters: |
+            relevant: ${{ env.RELEVANT_PATHS }}
+
   build-mobile:
     strategy:
       fail-fast: true

.github/workflows/ohos.yml

@@ -9,6 +9,18 @@ on:
   pull_request:
     branches: [develop, main, "ohos/**"]
     types: [opened, synchronize, reopened, ready_for_review]
+    paths:
+      - "Cargo.toml"
+      - "Cargo.lock"
+      - "rust-toolchain.toml"
+      - ".cargo/**"
+      - "easytier/**"
+      - "easytier-core/**"
+      - "easytier-proto/**"
+      - "easytier-rpc-build/**"
+      - "easytier-contrib/easytier-ohrs/**"
+      - ".github/workflows/ohos.yml"
+      - ".github/actions/**"
   workflow_dispatch:
     inputs:
       publish:
@@ -18,6 +30,7 @@ on:
         type: boolean
 
 permissions:
+  actions: write
   contents: read
   pull-requests: read
 
@@ -29,9 +42,24 @@ defaults:
     shell: bash
 
 jobs:
+  pre_job:
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
+    outputs:
+      should_skip: ${{ steps.skip_check.outputs.should_skip == 'true' && github.ref_type != 'tag' && github.ref_name != 'main' && !startsWith(github.ref_name, 'releases/') }}
+    steps:
+      - id: skip_check
+        uses: fkirc/skip-duplicate-actions@v5
+        with:
+          concurrent_skipping: 'same_content_newer'
+          skip_after_successful_duplicate: 'true'
+          cancel_others: 'true'
+          paths: '["Cargo.toml", "Cargo.lock", "rust-toolchain.toml", ".cargo/**", "easytier/**", "easytier-core/**", "easytier-proto/**", "easytier-contrib/easytier-ohrs/**", ".github/workflows/ohos.yml", ".github/actions/**"]'
+
   ohos:
     name: ohos
-    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
+    needs: pre_job
+    if: needs.pre_job.outputs.should_skip != 'true'
     runs-on: ubuntu-latest
 
     steps:
@@ -67,6 +95,13 @@ jobs:
           rustup component add rustfmt
           cargo fmt --all --manifest-path \
             easytier-contrib/easytier-ohrs/Cargo.toml -- --check
+          cargo test --locked --manifest-path \
+            easytier-contrib/easytier-ohrs/Cargo.toml \
+            -p easytier-ohos-core -p easytier-ohos-features \
+            --lib -- --test-threads=1
+          cargo check --locked --manifest-path \
+            easytier-contrib/easytier-ohrs/Cargo.toml \
+            -p easytier-ohrs --tests
 
           cargo_version=$(cargo metadata --format-version 1 --no-deps \
             --manifest-path easytier/Cargo.toml | jq -r '.packages[0].version')

.github/workflows/release.yml

@@ -18,7 +18,7 @@ on:
       version:
         description: 'Version for this release'
         type: string
-        default: 'v2.6.4'
+        default: 'v2.7.0'
         required: true
       make_latest:
         description: 'Mark this release as latest'

.github/workflows/test.yml

@@ -22,19 +22,40 @@ defaults:
 
 jobs:
   pre_job:
-    # continue-on-error: true # Uncomment once integration is finished
     runs-on: ubuntu-latest
-    # Map a step output to a job output
+    env:
+      RELEVANT_PATHS: >-
+        ["Cargo.toml", "Cargo.lock", "rust-toolchain.toml", ".cargo/**",
+        "pnpm-lock.yaml", "pnpm-workspace.yaml", "package.json", "easytier/**",
+        "easytier-core/**", "easytier-proto/**", "easytier-rpc-build/**",
+        "easytier-web/**", "easytier-gui/src-tauri/**",
+        "tauri-plugin-vpnservice/**", "easytier-contrib/**",
+        ".github/workflows/test.yml", ".github/actions/**"]
     outputs:
-      should_skip: ${{ steps.skip_check.outputs.should_skip }}
+      should_skip: >-
+        ${{
+          steps.skip_check.outputs.should_skip == 'true' ||
+          (
+            github.event_name == 'pull_request' &&
+            steps.path_filter.outputs.relevant != 'true'
+          )
+        }}
     steps:
       - id: skip_check
         uses: fkirc/skip-duplicate-actions@v5
         with:
-          # All of these options are optional, so you can remove them if you are happy with the defaults
           concurrent_skipping: 'never'
           skip_after_successful_duplicate: 'true'
-          paths: '["Cargo.toml", "Cargo.lock", "easytier/**", "easytier-core/**", "easytier-proto/**", "easytier-web/**", "easytier-gui/src-tauri/**", "easytier-contrib/**", ".github/workflows/test.yml", ".github/actions/**"]'
+          paths: ${{ env.RELEVANT_PATHS }}
+
+      - id: path_filter
+        if: >-
+          github.event_name == 'pull_request' &&
+          steps.skip_check.outputs.should_skip != 'true'
+        uses: dorny/paths-filter@v4
+        with:
+          filters: |
+            relevant: ${{ env.RELEVANT_PATHS }}
 
   check:
     name: Run linters & check

CONTEXT.md

@@ -90,3 +90,16 @@ A compact compatibility Host retains accepted values in the authoritative TOML
 model for management readback, while the shared host-aware normalization path
 omits capabilities that the compact runtime cannot execute. Omitted settings
 are silent no-ops and must not be advertised as live network capabilities.
+
+## Web compatibility Host
+
+The Web compatibility Host runs the portable EasyTier guest in JavaScript
+runtimes that provide WebAssembly JSPI. Its shared runtime Module owns guest
+lifecycle, Host capability operations, data-plane resources, and WebSocket
+message handling. Browser and Cloudflare Adapters own only the platform-specific
+way that WebSockets are dialed or accepted and the matching guest artifact.
+
+The Browser Adapter is an outbound-only EasyTier instance with a smoltcp TCP
+data plane. The Cloudflare Adapter is an inbound-only relay hosted by one named
+Durable Object. Their public configuration exposes only capabilities each Host
+can execute; guest ABI details and serialized TOML remain internal.

Cargo.toml

@@ -21,6 +21,76 @@ exclude = [
 edition = "2024"
 rust-version = "1.95"
 
+[workspace.dependencies]
+# Shared versions and sources; members select features and optional dependencies.
+anyhow = "1.0"
+arc-swap = "1.9"
+async-trait = "0.1.92"
+atomic-shim = "0.2.0"
+auto_impl = "1.3.0"
+base64 = "0.23"
+bon = "3.10.1"
+bytecodec = "0.5.0"
+bytes = "1.12.1"
+chrono = "0.4.45"
+cidr = "0.3.2"
+clap = "4.6.7"
+crossbeam = "0.8.5"
+dashmap = "6.2.1"
+easytier = { version = "2.7.0", path = "easytier", default-features = false }
+easytier-core = { version = "2.7.0", path = "easytier-core", default-features = false }
+easytier-ffi = { path = "easytier-contrib/easytier-ffi", default-features = false }
+easytier-proto = { version = "2.7.0", path = "easytier-proto", default-features = false }
+futures = "0.3"
+guarden = "0.3"
+hmac = "0.13.0"
+http-body-util = "0.1"
+hyper = { version = "1", default-features = false }
+hyper-util = { version = "0.1", default-features = false }
+indoc = "2.0.7"
+log = "0.4"
+mimalloc = "*"
+once_cell = "1.21"
+parking_lot = "0.12.5"
+percent-encoding = "2.3.2"
+pin-project-lite = "0.2.17"
+prost = "0.14.4"
+prost-types = "0.14.4"
+quanta = "0.12"
+# rand 0.10 / x25519-dalek 3 require a coordinated RNG trait migration.
+rand = "0.8.8"
+reqwest = { version = "0.13.5", default-features = false }
+rust-i18n = "4"
+rustls = { version = "0.23.45", default-features = false }
+# tower-sessions-sqlx-store 0.15 requires SQLx 0.8; SeaORM 2 requires SQLx 0.9.
+sea-orm = "1.1.20"
+sea-orm-migration = "1.1.20"
+serde = "1.0.229"
+serde_json = "1.0"
+sha2 = "0.11.0"
+smoltcp = { version = "0.14.0", default-features = false }
+sqlx = "0.8.6"
+strum = "0.28.0"
+stun_codec = "0.4.0"
+sys-locale = "0.3"
+tauri = "2.11.5"
+tempfile = "3.27.0"
+thiserror = "2.0"
+thunk-rs = { git = "https://github.com/EasyTier/thunk.git", default-features = false }
+tokio = { version = "1.53", default-features = false }
+tokio-rustls = { version = "0.26", default-features = false }
+tokio-util = "0.7.19"
+toml = "1.1.6"
+tower-http = "0.7"
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", default-features = false }
+url = "2.5"
+uuid = "1.26.1"
+winapi = "0.3.9"
+x25519-dalek = "2.0.1"
+# zerocopy 0.8 requires migrating the packet layout and casting APIs.
+zerocopy = "0.7.35"
+
 [profile.dev]
 panic = "unwind"
 debug = 2

README.md

@@ -300,6 +300,12 @@ sudo easytier-core --network-name mysharednode --network-secret mysharednode
 
 EasyTier is released under the [LGPL-3.0](https://github.com/EasyTier/EasyTier/blob/main/LICENSE).
 
+## Responsible Use
+
+Use EasyTier only for lawful purposes and in compliance with applicable laws
+and regulations. You are responsible for ensuring that you are authorized to
+connect to and administer the networks and devices involved.
+
 ## Sponsor
 
 CDN acceleration and security protection for this project are sponsored by Tencent EdgeOne.

README_CN.md

@@ -299,6 +299,10 @@ sudo easytier-core --network-name mysharednode --network-secret mysharednode
 
 EasyTier 在 [LGPL-3.0](https://github.com/EasyTier/EasyTier/blob/main/LICENSE) 许可下发布。
 
+## 使用规范
+
+请仅将 EasyTier 用于合法用途，并遵守适用的法律法规。使用者有责任确保其已获授权连接和管理相关网络与设备。
+
 ## 赞助
 
 本项目的 CDN 加速和安全防护由腾讯云 EdgeOne 赞助。

docs/core-architecture.md

@@ -184,12 +184,27 @@ wire codecs. It does not own socket I/O or connection policy.
 - DNS and DNS record resolution;
 - connector environment observations;
 - packet ingress and egress;
-- Host socket operation bridges and handle-based TCP/UDP/listener adapters.
+- Host socket operation bridges and handle-based TCP/UDP/listener adapters;
+- host-owned, message-preserving tunnel endpoints.
 
 Core owns scheduling, backpressure, cancellation, UDP session state, and
 protocol state even when each actual operation crosses a Host Adapter. A Host
 Adapter owns the real resource and performs the OS operation.
 
+For host-owned tunnels, ownership crosses the guest ABI only after a bounded
+Host listener queue accepts the tunnel. The queue is registered through
+`CoreHostAdapters` and consumed by the normal `CoreListenerRuntime`, so the
+tunnel still reaches `PeerAcceptedTunnelHandler` and cannot bypass peer
+handshake, admission, events, or routing policy. Each Host receive produces
+one complete `DummyTunnel` payload; no stream framing is added. The Host owns
+transport-specific message validation and maps a clean close to tunnel EOF.
+
+Hosts without outbound sockets select `CoreConnectivityMode::InboundOnly` for
+one instance. That startup plan retains listeners and the peer/router while
+omitting STUN, outbound connectors, and hole punching. Cargo features only
+compile Host Adapters; they do not change `CoreInstance` fields, lifecycle, or
+management semantics.
+
 The native `NativeHostRuntime` is process-wide and does not retain an instance
 `GlobalCtx`, namespace guard, socket mark, or connectivity state. Differences
 between instances travel in each request's `SocketContext`. A narrow

docs/data-plane-runtime-plan.md

@@ -5,9 +5,8 @@
 Accepted.
 
 This document is the implementation plan for restructuring the EasyTier data
-plane and exposing it through native FFI and the standalone
-`easytier-go-host` project. It describes a target architecture, not the current
-implementation.
+plane and exposing it through native FFI and the `easytier-go` module. It
+describes a target architecture, not the current implementation.
 
 The implementation scope is:
 
@@ -16,7 +15,7 @@ The implementation scope is:
   backend;
 - `easytier-contrib/easytier-ffi`;
 - the WASI guest ABI implemented by `easytier-core`;
-- `/data/project/easytier-go-host`;
+- `easytier-go`;
 - TCP, UDP, and smoltcp data-plane paths;
 - moving KCP route selection and source-connection ownership below the
   `DataPlaneRuntime` Interface without making KCP portable.
@@ -987,7 +986,7 @@ Repository: EasyTier.
 
 ### Phase 8: Go `coreabi` and engine
 
-Repository: `easytier-go-host`.
+Repository: EasyTier (`easytier-go`).
 
 - Add typed data-plane guest calls and wire codecs.
 - Extend the single driver with submit, cancel, close, and completion drain.
@@ -996,7 +995,7 @@ Repository: `easytier-go-host`.
 
 ### Phase 9: Go standard network Adapters and artifact
 
-Repository: `easytier-go-host`.
+Repository: EasyTier (`easytier-go`).
 
 - Add `Dial`, `Listen`, and `ListenPacket`.
 - Implement TCP, UDP, deadlines, cancellation, close, and error mapping.
@@ -1006,7 +1005,8 @@ Repository: `easytier-go-host`.
 - Run real two-instance TCP and UDP integration tests.
 
 Each phase ends in a reviewable commit. Commit messages use a 72-column text
-width. The complete task receives one final review across both repositories.
+width. The complete task receives one final review across both implementation
+areas.
 The operation-broker commit may receive an additional high-risk incremental
 review because it contains concurrency logic.
 

docs/easytier-web-managed-config-sync-plan.md

@@ -7,9 +7,9 @@
 - 上游依赖：后续由 Console 计算并发送 Patch
 - 兼容要求：保留现有 Full PUT
 
-本文记录当前接收端方案。Session 在能够证明 Patch base 与已应用 revision 连续时
-只收敛 touched instances；重启、通知丢失、revision 断链或并发积压时沿用 Full
-reconcile。
+本文记录当前接收端方案。Session 合并已持久化 Patch 的 touched instance IDs，
+并在运行态收敛时读取这些实例的最新持久化状态。重启、通知丢失或无法安全判断
+实例 ownership 时沿用 Full reconcile。
 
 ## 1. 背景与结论
 
@@ -30,8 +30,10 @@ Console 每次发布都会向该路径发送完整 Exact Set。实例很多时
 3. PATCH 使用 `expected_config_revision` 做 compare-and-swap（CAS）。
 4. Full/Patch 的配置变更与 revision 更新在一个 SQLite transaction 中提交。
 5. Patch 只查询和写入 touched instances，不扫描完整 Target。
-6. 写入成功后通知 Session 本次 base、target 和 touched instance IDs。
-7. Session 仅在 applied revision 精确匹配 base 时增量收敛，否则安全回退 Full。
+6. 写入成功后通知 Session 本次 expected、target 和 transaction 实际 touched
+   instance IDs。
+7. Session 只合并 revision 连续的 touched IDs，并以 SQLite 当前状态为准增量
+   收敛；可信 runtime base、通知链或 persisted target 无法证明连续时回退 Full。
 
 普通变更的接收端成本由：
 
@@ -371,20 +373,33 @@ revision。只影响 user-owned rows 的操作不清除 managed revision。
 - 只有带 target revision 的 `Applied` 才通知匹配的 live Session；
   `AlreadyApplied`、legacy unrevisioned Full、conflict 和失败不重复通知。
 - Notification 必须发生在 commit 之后。
-- Full notification 清除任何 pending delta，触发完整收敛。
+- Full notification 将 pending reconcile hint 提升为 Full，触发完整收敛。
 - Patch notification 携带 expected revision、target revision、upsert IDs 和本次
   transaction 实际接受删除的 web-owned IDs。请求删除但数据库原本不存在的 ID
-  仍是 no-op，不能借机删除 Core 中同 ID 的 user-owned 实例。只有 Session applied
-  revision 精确等于 expected revision，且没有更早的 Patch 等待处理时，才保留该
-  delta。
-- 两次 Patch 在前一次完成前积压时不合并 delta；Session 清除 pending delta，并在
-  最新 heartbeat/revision 上执行一次 Full。这避免引入 Patch queue 或 delivery FSM。
-- 增量 round 只读取 upsert rows，只删除本次 delete IDs，只对 touched running
-  instances 执行 runtime Patch/Run。完成前再次校验 persisted target revision；只有
-  全部 touched instances 成功且 target 仍相同，才推进 applied revision。
+  仍是 no-op，不能借机删除 Core 中同 ID 的 user-owned 实例。
+- Session 将尚未应用的 Patch touched IDs 合并为一个 Dirty set，并始终以 SQLite
+  最新 revision 下的 rows 为准。它不重放历史 Patch，也不维护 Patch queue 或
+  delivery FSM。只有 incoming expected 等于 pending target 的通知才能合并；Dirty
+  hint 保留最早 expected 和最新 target。乱序、不连续或无法证明顺序的通知将 hint
+  提升为 Full。多个连续 Patch 积压时，旧 round 由 runtime epoch 拦截，下一 round
+  直接收敛到最新 target。
+- Session 分开记录对外报告的 applied revision 和内部可信的 runtime base。开始任何
+  runtime side effect 前清除 applied；Patch round 的 side effects 完全包含在 Dirty
+  set 中，因此失败或被新通知拦截时仍保留最早 runtime base，以便按最新持久化状态
+  重试 Dirty set。Full round、direct mutation、授权失败或 Session ownership 中断会
+  清除 runtime base。
+- 只有可信 runtime base 等于 Dirty 最早 expected，并且 SQLite persisted revision
+  等于 Dirty 最新 target 时，才允许增量 round。重连后 runtime base 未知、通知
+  丢失，或 SQLite 已经提交了更靠后的 revision 而通知尚未送达时都回退 Full，避免
+  不完整的 Dirty set 把完整 target revision 误标为已应用。
+- 增量 round 逐个读取 Dirty set 中的最新 row。仍然存在且启用的 web-owned row
+  使用其最新 config；已经删除的 row 进入 delete set；遇到 disabled 或非 web-owned
+  row 时回退 Full，以保留 ownership 规则。完成前再次校验 persisted target
+  revision；只有全部 touched instances 成功且 target 仍相同，才推进 applied
+  revision。
 - 任何通过 EasyTier Web mutation route 直接 Run、Save、Delete 或切换实例状态的
   操作在执行前和结束后（包括部分 side effect 后返回错误）都清除 Session applied
-  revision 与 pending delta、增加运行配置 cache epoch，并唤醒一次 Full
+  revision、可信 runtime base 与 pending hint，增加运行配置 cache epoch，并唤醒一次 Full
   reconcile。旧 round 只有 epoch 仍匹配时才能推进 applied revision；新一轮不得
   信任 mutation 前缓存的 runtime config。否则 runtime-only mutation 或 Core 成功、
   SQLite 失败的复合 mutation 可能在 persisted revision 不变时破坏 Patch base 的
@@ -491,11 +506,13 @@ response 当作旧 receiver 并静默换一种 mutation contract；出现 404
 - 超限 Full 稳定返回 413/422，而不是耗尽进程内存；
 - 并发请求无 deadlock，且 CAS 结果确定。
 
-Session 测试还必须验证：精确 base/target 使用 touched-instance reconcile；base
-不匹配、目标 revision 已变化、Full notification 和 Patch backlog 都使用 Full；
-touched runtime apply 失败不推进 applied revision；删除只作用于本次 delete IDs。
-运行态 Config Get/Patch/Run/Delete 数量应随 touched instances 增长。为确认运行实例
-身份而进行的一次 list/meta RPC 可以保留，它不发送或重写所有实例配置。
+Session 测试还必须验证：连续 Patch 的 Dirty IDs 会合并且保留最早 expected；未知
+或不匹配的 runtime base、乱序/不连续通知使用 Full；增量 round 读取最新 row；已经
+删除的 web-owned row 只删除对应 Dirty ID；Full notification 覆盖 Dirty hint；目标
+revision 已变化或 touched runtime apply 失败时不推进 applied revision；直接 runtime
+mutation 使 revision 与运行配置 cache 同时失效。运行态 Config Get/Patch/Run/Delete
+数量应随 touched instances 增长。为确认运行实例身份而进行的一次 list/meta RPC
+可以保留，它不发送或重写所有实例配置。
 
 ## 11. Observability
 
@@ -523,9 +540,13 @@ Rollout acceptance：
 
 ### 12.1 Session runtime delta apply（已实现）
 
-Patch commit outcome 已携带 touched IDs。Session 只在 applied revision 正好等于
-Patch base 时执行 touched-instance reconcile；重启、revision 断链、通知丢失或
-并发 Patch backlog 都退回 Full。接收端不保存 Patch queue，也不合并 delta。
+Patch commit outcome 已携带 expected、target 和 transaction 实际 touched IDs。
+Session 只合并 expected/target 连续的 Dirty IDs，并在每一轮从 SQLite 读取最新
+target revision 对应的当前 rows；因此正常积压只增加 Dirty set，不需要保留中间
+revision 的 Patch queue。可信 runtime base 必须等于 Dirty 最早 expected；Patch
+side effect 失败可保留该 base 重试，通知丢失、乱序、进程重启或新 Session 尚无
+runtime base 时回退 Full。Full
+notification、disabled row 或 ownership 无法证明时也回退 Full。
 
 ### 12.2 Chunked Full
 

docs/kcp-control-reliability-design-2026-09-14.md

@@ -0,0 +1,470 @@
+# KCP 控制报文可靠性与旧版兼容设计
+
+日期：2026-09-14。
+
+状态：已按本文实现并提交；当前实现、验收结果及仍未定位的异常见
+[实现与验证记录](kcp-control-reliability-validation-2026-09-14.md)。
+本文保留设计要求，具体通过范围以验证记录为准。
+
+## 1. 背景与问题边界
+
+此前已修复 TCP 代理任一方向 EOF 导致双向转发提前退出、KCP accept
+通知队列满后连接交接丢失、接收缓冲排空与提前 FIN 的处理，以及握手前
+心跳触发 RST 的竞态。具体版本及结果见
+[半关闭验证记录](tcp-proxy-half-close-validation-2026-09-14.md)。
+
+仍有两个问题：
+
+1. 已证实的握手最终 ACK 丢失：源端收到 SYNACK 后认为连接建立，目标端
+   仍停留在 SynReceived；服务端先发 greeting 的业务因此超时。
+2. 一次未主动注入丢包的反向半关闭超时：发送端出现输出队列 Full，FIN
+   已进入端点输出队列，但没有证据证明它何时到达对端。失败日志未记录
+   客户端已收字节数，尚不能确定缺少的是数据、EOF，还是两者。后续
+   TRACE 重跑通过，不足以消除或解释原失败。
+
+KCP 数据传输自身的确认重传没有覆盖外层 SYN、SYNACK、握手确认和 FIN。
+这是连接状态机的局部协议设计问题。修复需要明确控制报文的重复处理、
+完成条件和状态寿命，无需重做 KCP 数据传输或 EasyTier 路由架构。
+
+本设计解决已证实的握手恢复缺口，并为 FIN 增加可靠确认。同时继续调查
+第二项异常；不能将新增 FIN 重传直接当作该异常已经修复的证明。
+
+## 2. 目标、范围与不变量
+
+目标：
+
+- 新旧节点双向正常互通，滚动升级不得要求所有节点同时升级。
+- 新节点之间，控制报文在重试预算内丢失、重复或乱序时能够恢复。
+- 连接只交接一次，应用数据不重复交付，EOF 不越过已接收数据。
+- 半关闭只关闭一个发送方向，另一方向仍可长期传输。
+- 无法恢复时有界结束并报告错误，不能用正常 EOF 掩盖失败。
+- 关闭记录、待发送控制报文和重试任务均有明确生命周期。
+
+范围：kcp-sys 的报文定义、连接状态机、端点调度与清理、必要的流错误
+传播，以及 EasyTier 的依赖 pin、集成测试和验证记录。
+
+不新增路由能力公告、PeerFeatureFlag 字段、配置开关或应用层请求重试；
+不修改 TCP flow-key 修复、QUIC 协议、KCP 数据分段和拥塞算法。保留现有
+connect API、调用方超时和业务测试的 5 秒 socket 超时。
+
+协议不变量：
+
+1. 模式由本连接握手确定，交付应用后不能切换。
+2. 握手状态变化和是否产生应答是两件事；可靠模式允许状态不变但应答。
+3. 已经进入应用交接路径的连接，重复控制包不能再次 accept。
+4. FIN_ACK 只确认对方 FIN，不表示自己也关闭发送方向。
+5. 只有正常收到对端 FIN 且排空接收数据，才能向应用报告正常 EOF。
+6. FIN 确认成功后，FIN 重试期限不能限制正常半关闭连接的寿命。
+7. 重复包不能延长握手、FIN 重试和最终关闭记录的固定截止时间。
+
+## 3. 版本基线与兼容证据
+
+| 用途 | kcp-sys revision |
+| --- | --- |
+| 旧协议基线 | `d7427c22d764deb1860a7d37acc446ed5033464c` |
+| 本设计实施基线，已含前述局部修复 | `b37ee660fb70bb6d816fb8bbc08b140e55e7218b` |
+
+源码检查确认：
+
+- 旧 header 含三个 u32、一个 flags 字节及一个 `rsv` 保留字节，总长
+  14 字节；旧实现不读取 `rsv`。
+- 旧 SYNACK 使用新建且清零的 header，不回显 SYN 的 `rsv`。
+- 旧 FSM 收到重复 SYN 时可能构造 RST，但状态不变；外层
+  `KcpConnectionState::handle_packet` 丢弃状态未变化时的输出，
+  因此已检查的旧端点不会实际发送该 RST。
+- `rsv` 未被读取、状态不变时抑制输出的行为，在已检查历史
+  `a5f4b4e`、`37f653c`、`0f2fea1`、`9ce5c08`、`0f0a055`、
+  `71eff18`、`d7427c2` 中一致。
+
+这些是源码与历史检查，不是上述每个 revision 的运行测试。正式兼容
+声明必须对应实际测试的 EasyTier 版本及其锁定依赖，不能扩展为所有
+未检查的历史版本或第三方修改版本都已验证。
+
+实现基线源码：
+[报文定义](https://github.com/EasyTier/kcp-sys/blob/b37ee660fb70bb6d816fb8bbc08b140e55e7218b/src/packet_def.rs)、
+[状态机](https://github.com/EasyTier/kcp-sys/blob/b37ee660fb70bb6d816fb8bbc08b140e55e7218b/src/state.rs)、
+[端点](https://github.com/EasyTier/kcp-sys/blob/b37ee660fb70bb6d816fb8bbc08b140e55e7218b/src/endpoint.rs)。
+
+## 4. 报文格式与连接内协商
+
+### 4.1 字段定义
+
+保持 14 字节 header、连接标识字段、已有 flags 和 KCP DATA payload
+布局不变。使用已有 `rsv` 字节：
+
+| 值 | 定义 |
+| --- | --- |
+| `0` | 旧协议，后文称 legacy |
+| `1` | 本文可靠控制协议，后文称可靠模式 |
+
+新增 FIN_ACK 使用 flags 当前未分配的最高位 `0x80`。它是独立报文，
+flags 必须恰好为 FIN_ACK，`rsv=1`，payload 为空。不能用 FIN|ACK
+表示关闭确认，因为旧端会把 FIN 位解释为对端关闭发送方向。
+
+可靠模式报文约束：
+
+| 报文 | flags | payload |
+| --- | --- | --- |
+| SYN | SYN | 原有连接元数据，重传保持完全相同 |
+| SYNACK | SYN\|ACK | 空 |
+| 最终握手确认 | ACK\|DATA | 空 |
+| 数据及 KCP 内部确认 | ACK\|DATA | 原有 KCP payload |
+| 关闭发送方向 | FIN | 空 |
+| 关闭确认 | FIN_ACK (`0x80`) | 空 |
+| 重置、心跳 | 原有 RST、PING、PING\|PONG | 沿用现有定义 |
+
+可靠模式报文均带 `rsv=1`。legacy 的后续报文仍使用现有格式和 `rsv=0`；
+新源端最初提出协商的 SYN 是可能发给旧目标端的唯一保留字节扩展。
+
+只有匹配连接标识、当前握手阶段和合法 flags/payload 的 SYNACK，
+才可以确认模式。不能通过 PING/PONG 确认：旧端的心跳应答会复制输入
+报文，可能保留它并不理解的 `rsv`。
+
+### 4.2 协商步骤
+
+1. 新源端发送 SYN，`rsv=1`，进入尚未确认模式的 SynSent。
+2. 新目标端收到 SYN：`rsv=1` 时回复 SYNACK `rsv=1`，记录可靠模式
+   候选状态；`rsv=0` 时从头使用 legacy，回复 SYNACK `rsv=0`。
+3. 旧目标端忽略 `rsv`，自然回复 SYNACK `rsv=0`。新源端收到它后，
+   在交付应用前确定 legacy，最终 ACK 及后续报文都使用旧模式。
+4. 新源端收到合法 SYNACK `rsv=1` 后确认可靠模式，发送最终 ACK
+   `rsv=1`。目标端收到匹配模式的确认后完成握手并登记待 accept。
+5. 源端继续在收到合法 SYNACK 后完成 connect，不增加第四次握手或
+   额外 RTT。最终 ACK 丢失后的恢复规则见第 5 节。
+
+未识别的 SYN `rsv` 值不得被当作可靠能力，可按不支持扩展响应 legacy
+SYNACK。新源端只接受它实际支持的 SYNACK 模式 `0` 或 `1`；未知值
+报告协议错误，不启用增强行为。重复 SYN 不允许更改已有连接的模式或
+连接元数据。已协商可靠模式后，模式不匹配的控制包不得触发降级。
+
+节点重启或降级后的新连接重新协商；不缓存按节点永久生效的协议模式。
+不承诺跨进程重启维持既有连接。
+
+### 4.3 初始 SYN 与旧版兼容
+
+首个 SYN 或 SYNACK 丢失时，源端尚不可能拿到协商确认。因此 SynSent
+期间允许在原截止时间内重传完全相同的 SYN，不以前置能力公告或已收到
+SYNACK 为条件。
+
+在已检查的旧端点中，重复 SYN 不引出 RST，但也不会让旧目标端重发
+SYNACK。所以新源端→旧目标端仍保留旧目标端 SYNACK 丢失时的限制。
+这一行为必须由真实旧依赖运行测试确认，不能只测试重写的 legacy 模型。
+
+新目标端对旧源端保持 legacy 行为，不主动开启 SYNACK 重传。
+legacy 分支继续保留“状态不变则抑制 FSM 输出”的现有行为；不得将
+可靠模式的应答修复无条件套用，否则会改变旧连接的 RST 行为。
+
+## 5. 可靠握手与重复报文
+
+源端在 SynSent 重传 SYN，目标端在可靠 SynReceived 重传 SYNACK。
+所有重传使用原连接 ID，不创建额外连接或重试业务请求。
+
+| 当前状态 | 输入 | 动作 |
+| --- | --- | --- |
+| 无状态 | 合法 SYN | 保存模式与连接元数据，建立 SynReceived，回复 SYNACK |
+| SynReceived | 相同 SYN | 重新回复 SYNACK，不替换状态或延长截止时间 |
+| SynReceived | 匹配的 ACK\|DATA | 完成握手，登记待 accept 一次，停止 SYNACK 定时重传 |
+| SynSent | 合法 SYNACK | 确定模式，发送最终 ACK，完成 connect |
+| Established 或半关闭 | 重复 SYNACK | 回复最终 ACK，不重新创建流、不改变关闭状态 |
+| 已握手、尚未最终释放 | 相同 SYN | 可重发原 SYNACK，不重复 accept、不恢复已关闭方向 |
+| 已握手 | 重复最终 ACK | 幂等处理，不重复交接连接 |
+
+ACK\|DATA 带有效 KCP payload 时仍按 KCP 处理。若它同时完成握手，
+不得为了修复握手而重复交付 payload；必须验证 accept 前到达数据时，
+现有 KCP 重传和接收路径最终完整交付字节。
+
+最终 ACK 丢失的正常恢复：
+
+```mermaid
+sequenceDiagram
+    participant S as 源端
+    participant D as 目标端
+    S->>D: SYN
+    D->>S: SYNACK
+    S--xD: 最终 ACK 丢失
+    Note over S: connect 已返回
+    Note over D: 保持 SynReceived
+    D->>S: 重传 SYNACK
+    S->>D: 重发最终 ACK
+    Note over D: 登记待 accept 一次
+```
+
+### 5.1 最终 ACK 丢失后立即 FIN
+
+空流的发送缓冲本来就是空的，connect 返回后可以立即 shutdown；不能
+假设 FIN 一定晚于最终 ACK 到达。
+
+可靠 SynReceived 收到匹配模式和连接标识的合法 FIN 时，将它视为
+隐含的握手确认，同时执行：
+
+1. 完成握手并停止 SYNACK 重传。
+2. 登记待 accept 一次，保存对端发送方向已关闭。
+3. 回复 FIN_ACK；accept 创建流时继承对端关闭状态。
+4. 接收排空后报告 EOF，本端仍可回复数据。
+
+不能先进入 Closed 再返回 RST，也不能要求应用先发送非空数据才能
+完成握手。该规则仅用于可靠模式。
+
+## 6. FIN、确认与双向关闭
+
+### 6.1 本端关闭发送方向
+
+保留现有顺序：应用关闭发送队列，发送任务把排队数据交给 KCP，并等待
+`waitsnd == 0`，然后进入 FIN 待确认阶段。重试预算从这一阶段开始计算，
+不能从应用开始传输或尚未排空数据时开始计算。
+
+FIN 发送入队成功不代表对端已收到。记录待确认状态、下一次重传时间和
+固定截止时间，直到收到有效 FIN_ACK 或连接明确失败。收到对端 FIN
+本身不等同于本端 FIN 已被确认。
+
+保留现有 AsyncWrite shutdown 的本地关闭语义，不将其返回成功解释为
+对端已确认。关闭确认和最终回收由端点负责；后续超时通过仍存活的流和
+诊断状态表达，不能变成伪造的正常 EOF。
+
+### 6.2 收到 FIN 或 FIN_ACK
+
+- 收到 FIN：记录对端发送方向已关闭，并安排 FIN_ACK。接收任务仍需
+  把已确认接收的数据交给应用，排空后才产生 EOF。
+- FIN_ACK 可以先于应用读完数据发送；它确认端点收到了 FIN，不确认
+  应用已经消费数据。因此接收状态和缓冲生命周期不能随确认提前删除。
+- 重复 FIN：重复应答 FIN_ACK，不重复产生应用 EOF，不重置连接。
+- 收到 FIN_ACK：仅当本端确实已经发送 FIN，且模式、连接标识、flags
+  和 payload 全部合法时，停止本端 FIN 重传。
+- 提前、重复或与当前阶段无关的 FIN_ACK 不推进状态、不关闭写方向。
+
+发送和接收两个方向分别记录完成情况。现有 Established、LocalClosed、
+PeerClosed、Closed 不足以单独表达“本端 FIN 已发但未确认”，应在现有
+连接状态内补足该信息，不另建一套连接所有权或通用重试框架。
+
+### 6.3 正常回收与短暂关闭记录
+
+可靠模式最终回收分两步：
+
+1. 本端 FIN 已确认、对端 FIN 已收到，并且接收任务排空后，释放 KCP
+   数据对象、应用通道和数据任务；在原 state_map 保留最小关闭记录。
+2. 固定保留期结束后删除该记录。重复报文不延长保留期。
+
+关闭记录仅保存原连接 ID、协议模式、正常关闭原因、回复重复 FIN 所需
+信息和过期时间。它继续回复 FIN_ACK；合法在途 PING/PONG 可以忽略，
+不得因现有 Closed 心跳路径而回复 RST。迟到 SYN/SYNACK 不得重新
+accept、创建数据对象或恢复连接；已经完成的数据包可以丢弃。
+
+双方同时关闭时，即使只有一方收到 FIN_ACK，先完成的一方也要依靠该
+记录继续回答另一方的 FIN 重传。不能沿用“Closed 且 recv_done 就立即
+删除所有状态”的判断。
+
+legacy 继续使用原有回收规则。可靠模式的短暂记录会使状态表在有限
+时间内多保留条目，容量验收必须单独计算，不能继续要求所有内部状态
+在原 15 秒观察点清零。
+
+## 7. 定时、队列与失败路径
+
+### 7.1 拟定默认参数
+
+以下为实现初值，需由定点丢包与延迟测试验证后固定；调整须在验证记录
+说明，不能为了让测试通过而延长业务超时。
+
+| 参数 | 初值 / 规则 |
+| --- | --- |
+| SYN、SYNACK、FIN 首次重传间隔 | 200 ms |
+| 后续重传 | 指数退避，单次间隔上限 2 s |
+| 源端握手期限 | 调用方现有 `connect(timeout_dur)`，不延长 |
+| 可靠目标端握手期限 | 首次收到 SYN 后 60 s，不由心跳或重复包续期 |
+| FIN 待确认期限 | 进入 FIN 阶段后 60 s |
+| 正常关闭记录保留期 | 65 s，覆盖 FIN 重试窗口并留调度余量 |
+
+目标端和 FIN 的 60 秒预算是端点控制状态的资源边界，不替代应用更短的
+超时。网络永久不可达时，正确结果是可诊断的超时和最终清理。
+
+关闭记录保留期必须不少于另一端允许的最大 FIN 重试窗口加余量，因此
+FIN 期限不能变成各端任意可调且互不知情的参数。若后续版本改变这些
+上界，需要重新审查版本间兼容性。
+
+FIN 已确认后立即解除 FIN 重试期限；正常半关闭继续按既有连接存活规则
+处理。仅本端 FIN 未确认才受该期限限制，反向有数据或 PONG 也不能使
+未确认 FIN 无限续期。
+
+### 7.2 端点调度与输出队列
+
+使用单个端点控制调度任务和现有 state_map；不为每次重传创建任务，不
+扩容或改成无界队列。按最近的控制截止时间唤醒，新状态通过通知更新
+调度；没有待处理控制状态时，避免对全部空闲连接进行高频扫描。
+
+状态记录是控制报文待处理事实的来源。输出队列暂满时保留该事实，稍后
+再尝试；不能像原 accept 通知一样丢失后就再无恢复机会。
+
+- 用短临界区和非阻塞入队，禁止持有 state_map/conn_map 锁跨 await。
+- 每次实际入队前重新检查状态、连接标识和期限，防止陈旧重传在取消或
+  回收后继续发送。回收不能与入队检查形成复活旧连接的竞态。
+- SYN/SYNACK/FIN 的重传受各自固定预算限制。重复请求所需的 ACK 或
+  FIN_ACK 应答可合并为待发状态，不能累计无界报文列表。
+- 应答暂时无法入队时由调度器继续尝试；应答不会获得独立的无限寿命。
+  合并应答记录从首次待发起最多保留 60 秒，重复请求不续期；正常关闭
+  记录中的应答还受该记录更早的截止时间限制。入队成功即撤销待发标记。
+  单纯的应答待发过期只清除该应答，不因此关闭仍合法存活的连接；请求
+  发送方最终依靠自身握手或 FIN 重试期限判定成功或失败。
+- 队列满不能阻塞整个控制调度任务，也不能阻止它处理其他连接的截止
+  时间。不得把“尝试入队成功”统计成“对端确认成功”。
+
+### 7.3 取消、错误与连接 ID
+
+- connect future 取消或超时：撤销该连接的重试与本地所有权；目标端
+  未完成握手的状态按其固定期限退出，重复包不能延长。
+- 有效 RST、端点销毁或 FIN 重试耗尽：停止控制重试、唤醒等待任务，
+  保留错误与正常 EOF 的区别。只发送必要的现有重置通知，不建立 RST
+  确认和重试协议。
+- 清理失败连接不能重新产生待 accept；迟到的控制响应不能恢复已取消
+  的 connect future。
+- ConnId 分配必须避开所有仍有效的状态，包括正常关闭记录。回绕不能
+  复用仍在保留期内的 ID；会话标识变化后，旧报文不得作用于新会话。
+- 保留期之后无限迟到的包不在可靠恢复窗口内。不得通过永久保存关闭
+  记录来试图覆盖无界的网络延迟。
+
+## 8. 兼容性矩阵与降级
+
+| 源端 | 目标端 | 预期模式 | 必须满足 |
+| --- | --- | --- | --- |
+| 旧 | 旧 | legacy | 对照基线，保留既有行为 |
+| 新 | 旧 | SYNACK `rsv=0` 确定 legacy | 正常互通，不发 FIN_ACK，不要求目标支持新确认 |
+| 旧 | 新 | 从 SYN `rsv=0` 确定 legacy | 正常互通，不主动开启新 SYNACK/FIN 重传语义 |
+| 新 | 新 | 本连接握手确认可靠模式 | 握手与关闭在重试预算内恢复 |
+
+兼容的含义是旧节点仍可互通，且混合组合不因新代码发生行为退化。它不
+意味着旧目标端自动获得 accept 修复，或旧连接获得其未实现的 ACK/FIN
+恢复能力。必须把遗留失败与新增失败分别记录。
+
+发布或回退影响后续新连接的协商。协议模式固定在连接内，禁止基于后续
+路由公告变化对活跃连接进行升级或降级。旧可执行程序重启后不承担继续
+解释原进程可靠模式连接的义务。
+
+## 9. 实施拆分
+
+实施使用独立协议修复分支，以 `b37ee660` 及 EasyTier 当前已验证修复
+为基线，不将协议改动混入原 TCP flow-key patch。
+
+1. **先建立兼容测试夹具。** 使用实际旧依赖和当前基线端点，确认 `rsv`
+   处理、旧 SYNACK、重复 SYN 和旧模式输出门控。明确失败基线。
+2. **实现协商及状态处理。** 增加模式、合法报文校验、可靠模式幂等应答，
+   保留 legacy 路径。补上最终 ACK 丢失加立即 FIN 的交叉状态。
+3. **实现统一控制调度及可靠关闭。** 补足握手/FIN 期限、FIN_ACK、正常
+   关闭记录、队列暂满、取消和错误清理。
+4. **完成依赖验证后接入 EasyTier。** 更新依赖 pin 与锁文件，运行真实
+   代理路径、混合版本和跨平台验证，提交可追溯记录。
+
+协商声明代表完整可靠控制协议，不能在只实现握手恢复、尚未实现 FIN_ACK
+时对外声明 `rsv=1`。中间提交可以用于审阅，但仅完整实现且验证通过的
+依赖版本可被 EasyTier 发布使用。
+
+代码主要落点为 kcp-sys 的 `packet_def.rs`、`state.rs`、`endpoint.rs`，
+按实际错误传播需要调整 `stream.rs`；不预先拆出通用协议框架。EasyTier
+预计只需依赖更新、测试和记录，不需要修改 protobuf 或节点能力公告。
+
+## 10. 验证与验收标准
+
+### 10.1 确定性协议测试
+
+在端点输入/输出之间设置测试用报文过滤器，按连接 ID、报文类型和次数
+精确丢弃、延迟或重复报文。可使用可控时钟测试期限，不依赖随机 netem
+才能触发边界，也不通过扩大生产超时使测试通过。
+
+| 场景 | 验收断言 |
+| --- | --- |
+| 分别丢首个 SYN、SYNACK、最终 ACK | 新新组合恢复，同一连接只交接一次 |
+| 连续丢多次控制包后恢复链路 | 截止时间内恢复，重试次数与退避符合预期 |
+| 最终 ACK 丢失后空流立即 FIN | 目标完成握手、返回 EOF、仍能回复数据，无 RST |
+| 最终 ACK 丢失后首个 DATA 到达 | 正确完成握手，应用字节完整且不重复 |
+| 重复 SYN/SYNACK/ACK，含半关闭阶段 | 不重复创建连接，不恢复已经关闭的方向 |
+| 丢单向 FIN 或 FIN_ACK | 重传恢复；确认不关闭另一方向 |
+| 双方同时 FIN，单侧或双侧确认丢失 | 正确排空，正常关闭记录继续应答，最终回收 |
+| FIN 先于 accept 或 connect 返回 | 空请求、空响应均正确得到 EOF |
+| 接收缓冲尚未被应用读完 | FIN_ACK 不导致缓冲和数据任务提前释放 |
+| FIN 已确认后持续半关闭超过 60 s | 反向仍可传输，不受 FIN 期限误杀 |
+| 正常关闭记录收到重复 FIN、旧心跳 | 应答或忽略，无 RST，不延长固定保留期 |
+| SYN/FIN 永久丢失、控制输出队列长时间满 | 到期退出，无无限任务或状态残留 |
+| 队列临时满后恢复 | 待发事实不丢失，其他连接和清理继续运行 |
+| connect 取消、RST、端点销毁与重试并发 | 不复活旧状态，等待者正确结束，无伪 EOF |
+| ConnId 回绕、会话变化、迟到报文 | 不命中仍在保留期的旧 ID，不污染新会话 |
+
+### 10.2 真实旧版兼容测试
+
+测试夹具必须运行旧依赖的真实 endpoint，不能只在新实现上设置 legacy
+标志代替旧版本。首次验收覆盖 `d7427c2`、`b37ee660` 与新实现的组合，
+并记录 EasyTier 发布验证实际选用的旧二进制版本和哈希。
+
+除四种组合的双向数据与关闭外，额外断言：
+
+- 旧端收到 SYN `rsv=1` 仍按旧协议回复 SYNACK `rsv=0`。
+- 重复 SYN 不引出混合连接新增 RST；legacy 输出门控保持原有行为。
+- 混合组合捕获不到 FIN_ACK；旧端不必识别任何新控制语义。
+- PING/PONG、错误连接 ID、非法 flags 或未知 SYNACK 模式不能确认能力。
+- 新连接在节点升级、回退后重新选择正确模式，不沿用节点级缓存。
+- 旧版原有半关闭或丢包失败作为对照保留，不将它们写成新协议已通过。
+
+### 10.3 EasyTier 流量与平台验证
+
+Linux 需要 root 的测试在现有 `rust` 容器中运行。复用正常 target，权限
+问题通过修复所有权解决，不另开编译目录。
+
+- 完整三节点组合及 ACL、配置更新、端口转发、断连测试。
+- TCP/KCP/QUIC × 内核/smoltcp 六种模式，检查未修改协议没有退化。
+- 每组合 300 次短连接、16 并发、5 秒 socket 超时；KCP 每栈追加三轮，
+  与已有每版本 2,400 次 KCP 结果对照。
+- 空请求、256 KiB 请求后 EOF、1 MiB 响应，以及服务端先半关闭后客户端
+  才发送 256 KiB 的反向场景，均逐字节核对。
+- `netem delay 10ms 3ms loss 1%` 下持续双连接与短连接；定点控制包丢失
+  由协议测试证明，随机丢包实验用于验证整体行为。
+- 新旧两方向真实二进制互通；无丢包与丢包结果分别记录。
+- Linux、macOS、Windows 原生依赖测试及网关测试；格式与严格 Clippy。
+  缺少组件、未运行的项目不得记录为通过。
+
+### 10.4 未解释的反向超时
+
+复现脚本必须记录超时时已收到的字节数、是否收到 EOF、源端口、连接 ID，
+并在双方记录 FIN/FIN_ACK 的入队、发送和接收时间。补足原失败缺少的
+证据，区分数据缺失、关闭通知缺失、队列延迟和状态处理错误。
+
+恢复实际链路的 FIN 丢失，只能证明这一类注入故障已修复；仍需解释原
+异常或明确保留未定位项。不得用重跑通过覆盖原始失败。
+
+### 10.5 资源与交付门槛
+
+分别统计：应用代理连接、KCP 数据对象、半开握手、未确认 FIN、正常关闭
+记录、FD 和 RSS。保留期内的轻量记录属于设计成本，不能混同于活跃连接
+泄漏；其数量约受每秒关闭连接数乘以保留期约束，需实测内存成本。
+
+静止并超过握手/FIN 期限及关闭记录保留期后，所有应回收状态必须消失。
+使用重复负载周期检查资源是否持续累积，并检查端点空闲及大量并发时
+控制调度的 CPU 成本。不能仅凭一次 FD 回到基线宣布不存在泄漏。
+
+交付必须满足：确定性恢复用例通过；实际旧版兼容用例没有新增失败；
+错误路径有界清理；原有矩阵没有新退化；所有异常如实保留。完整最终
+代码 diff 由独立子代理审查，只处理高置信度真实缺陷。验证记录绑定
+提交、依赖 revision、二进制哈希、准确命令及原始日志。
+
+## 11. 当前进度与证据
+
+已完成：连接级版本协商、握手与 FIN 恢复、FIN_ACK、重复控制处理、
+正常关闭记录、队列饱和处理与取消清理。kcp-sys 最终提交为
+`3ef5c4161faf99940f3ed51efd43cef0cbc02b4f`，EasyTier 最终依赖接入为
+`ee02b8f7`。首次验收已测试真实旧实现 `d7427c2` 和 `b37ee660`。
+后续测试整理仅保留 `d7427c2` 长期基线；当前维护版本与依赖 pin 见
+[实现与验证记录](kcp-control-reliability-validation-2026-09-14.md)。
+
+三平台原生依赖测试、Linux 完整矩阵及实际流量的本轮结果单独记录，
+不沿用上一轮局部修复的通过数。最终代码审查没有 blocker / major，
+一项首次 SYNACK 调度竞态 minor 按用户规则记录待办。
+
+仍需保留的边界：原反向超时没有足够证据做最终归因；混合版本保留
+legacy 的控制恢复限制；有限负载和应用级资源采样不能代替生产规模
+长期内存、CPU 和容量验证。所有实测异常及未执行项见关联验证记录。
+
+此前调查原始产物位于：
+
+```text
+/data/project/proxy-close-validation-20260914/
+```
+
+关键证据：`remaining-loss-handshake.md`、`loss-handshake-evidence.log`、
+`delivery-reverse-timeout.md`、`fin-send-path-old-new.txt`、
+`delivery-manifest.json`、`traffic-summary.md`。上述绝对路径是本机
+调查产物位置；仓库读者可通过关联验证记录了解结论与证据限制。

docs/kcp-control-reliability-validation-2026-09-14.md

@@ -0,0 +1,296 @@
+# KCP 控制报文可靠性实现与验证（2026-09-14）
+
+本文记录
+[协议设计](kcp-control-reliability-design-2026-09-14.md)
+的实现与验证，独立于此前的 TCP flow-key 和半关闭局部修复。
+
+## 兼容测试维护整理
+
+当前维护版本为 kcp-sys `268533568d734ae89dc89603078da3ca522effe1`。
+保留 `d7427c22` 作为长期兼容基线，移除中间版本 `b37ee660` 的
+`kcp-sys-baseline` dev-dependency 与三项重复用例；单次使用的宏展开为
+普通测试函数。四项旧版兼容测试继续覆盖能力协商、双向数据、半关闭及
+重复 SYN；15 项 library 与 12 项协议回归不变。
+
+整理后 Linux 共 31/31 测试通过，格式与严格 Clippy 通过。EasyTier
+同步依赖 pin 与锁文件，并通过 `cargo +1.95 check --locked -p easytier
+--features full`。此次只整理测试与测试依赖，协议源码未改变。
+历史三平台 34/34 和全部流量结果仍属于下述 `3ef5c416` 实现验证，
+没有重写为整理后版本的执行结果。中间基线作为调查证据保留在本文。
+本次日志位于 `/data/project/kcp-compat-cleanup-validation/`。
+
+## 版本与实现
+
+- kcp-sys 基线：`b37ee660fb70bb6d816fb8bbc08b140e55e7218b`。
+- kcp-sys 初版实现：`c84733d4479b40a299d51f4c5b8bb02ccacadc68`。
+- kcp-sys 最终实现：`3ef5c4161faf99940f3ed51efd43cef0cbc02b4f`，补齐
+  可靠模式下未知连接 RST 输出队列饱和时的非阻塞处理。
+- EasyTier 基线：`851e7523`；接入提交：`4fedbdd1`、`ee02b8f7`，
+  仅修改依赖 pin 和 Cargo.lock。
+- 最终真实流量二进制：`final-easytier-core`，SHA-256：
+  `962f2480cb611ceb6cab293560d0dfb337218594cdc298a08f0e83801a2d17b8`。
+  它在接入提交前构建，源码及依赖内容与该提交一致；识别产物以哈希和
+  依赖 revision 为准，不单凭内嵌的 EasyTier git 版本字符串。
+
+依赖已发布到 `EasyTier/kcp-sys` 的独立分支
+`fix/control-reliability-20260914`，远端引用核对为上述最终 revision。
+EasyTier 任务分支为 `fix/kcp-control-reliability`。
+
+实现保留 14 字节 header，通过 SYN/SYNACK 的 `rsv` 协商可靠控制模式。
+收到旧 SYNACK 后固定使用 legacy，旧源端连接新目标端也从头使用 legacy。
+只有协商为可靠模式的连接使用独立 FIN_ACK 和新增恢复逻辑。
+
+可靠模式在原连接 ID 上恢复 SYN、SYNACK 和 FIN；重复握手不重复交接。
+最终 ACK 丢失后的空 FIN 可以同时确认握手并报告对端半关闭，反向仍能
+发送数据。FIN_ACK 只确认收到 FIN，不关闭本端发送方向，也不提前释放
+尚未被应用读取的接收数据。
+
+控制请求和待发送应答在原连接状态中保存，由端点统一调度。输出队列
+暂满不会丢失待发事实或延长固定期限；取消 connect 同步撤销本地状态。
+状态检查、控制入队和清理保持一致锁序，不持锁跨 await。
+
+初始重传间隔 200 ms、指数退避至 2 s；源端使用调用方连接超时，目标端
+握手及 FIN 待确认期限为 60 s。正常双向关闭且接收排空后释放数据对象，
+原状态表保留 65 s 的关闭记录，继续应答重复 FIN，并避免迟到心跳引出
+RST。FIN 一旦确认，正常半关闭不受 FIN 重试期限限制。
+
+## 自动化结果
+
+| 验证 | 结果 |
+| --- | --- |
+| Linux kcp-sys | 15 library + 12 协议回归 + 7 真实旧依赖兼容，34/34 |
+| macOS kcp-sys | 相同 34/34，两个 example target 通过 |
+| Windows kcp-sys | 相同 34/34，两个 example target 通过 |
+| Linux 两个 example target、格式、严格 Clippy | 通过 |
+| macOS 格式、严格 Clippy | 通过 |
+| Windows 格式、Clippy | 所选 stable 缺少组件，未执行 |
+| Linux 原生网关测试 | 200/200 |
+| macOS、Windows 原生网关测试 | 各 200/200 |
+| EasyTier 完整三节点及补充集成测试 | 276/276，834.639 s |
+| EasyTier Linux 严格 Clippy | 通过 |
+
+macOS 首次获取依赖遇到 GitHub TLS 错误，随后导入本机真实 Git 对象与
+checkout，在依赖 revision 不变的情况下离线测试；没有改成 path 依赖，
+也没有用新实现替换旧依赖。Windows 原始日志为 UTF-16LE，另保存 UTF-8
+副本。两平台复用原 target，没有另开编译目录绕过权限问题。
+
+协议修改集中在 kcp-sys，EasyTier core 源码没有变化。原生网关验证检查
+与现有相同 core 源码的兼容行为，不能替代上面的真实新旧 KCP 端点测试。
+远端应用 manifest 仍锁定旧依赖 `d7427c2`，网关命令只选择 easytier-core；
+关键转发文件 `tcp_proxy_service.rs` 哈希与本地一致。因此不能将这组
+网关测试描述为完整原生应用已经接入最终新依赖。
+
+## 失败到通过的对照
+
+- 丢弃第一份最终握手 ACK：基线客户端 connect 返回，服务端 accept
+  超过 5 s 仍未完成；实现后约 0.25 s 恢复，并成功发送服务端 greeting。
+- 新源端连接真实旧依赖：基线仅因 SYN 尚未声明协商能力而未达到新协议
+  测试要求；实现后 SYN 提出 `rsv=1`、旧 SYNACK 回复 `rsv=0`，后续
+  数据与关闭均走 legacy。该项验证协商功能，不把它描述为旧版互通 bug。
+- 原有 RST 单测曾在新连接上注入 `rsv=0` 的合成 RST，因可靠模式拒绝
+  不匹配模式而超时；测试改为注入该连接实际协商版本的 RST 后通过。
+  模式不匹配的报文不能用于证明正常 RST 错误传播失败。
+- 新增双向大缓冲夹具最初单次写入超过既有 KCP send 的分片限制，出现
+  `Err(-2)`。调整为与原有测试一致的 16 KiB 分块，仍验证双向各
+  200 KiB 总数据和原 5 s 期限；本补丁没有修改既有单次大写入限制。
+
+- 最终补查发现初版 `c84733d` 对未知可靠 FIN 的 RST 仍使用阻塞发送。
+  填满输出队列后，新 SYN 不能在 100 ms 内进入状态表；改为可靠模式
+  的无状态应答使用 try_send 后通过。需要重试的有状态控制仍由状态表
+  保管；legacy 发送路径不变。
+
+原始失败日志保留，未使用扩大业务超时或重跑通过覆盖失败记录。
+
+## 协议与生命周期覆盖
+
+12 项公有 API 协议回归使用真实端点及按报文类型过滤的链路：
+
+- 连续丢 SYN、连续丢 SYNACK、丢最终 ACK 后的服务端 greeting。
+- 所有空最终 ACK 均丢失，空 FIN 直接完成握手，EOF 后仍可回复。
+- 单向 FIN 或 FIN_ACK 丢失，另一方向仍可传输。
+- 双向 200 KiB 缓冲、双方首个关闭确认丢失、延后读取与排空。
+- 半关闭后重复 SYN/SYNACK/ACK；握手 ACK 丢失时 DATA 乱序、重复。
+- FIN 确认后推进 61 s，再恢复实际时钟，仍可反向传输。
+- PONG 保留 `rsv=1`、非法 SYNACK flags、非空 SYNACK 均不能确认模式。
+- 未知 SYNACK version 返回 `InvalidProtocolVersion`，不启用新模式。
+
+15 项 library 测试包含原有 10 项以及五项生命周期与队列测试：取消 connect
+立即释放状态；重复 SYN 与满输出队列不延长半开期限；未确认 FIN 超时
+唤醒读端并释放状态；正常关闭记录应答迟到包、不引出 RST、不被延长，
+保留期间跳过相同 ConnId，期满后删除旧记录而不影响新连接；满输出
+队列下未知可靠 FIN 不能阻止后续 SYN 进入握手。
+
+可控时钟只用于测试期限，不修改生产时间常量。数据测试仍通过实际 KCP
+发送、接收及 AsyncRead/AsyncWrite 路径。
+
+## 真实旧依赖兼容
+
+dev-dependency 固定并实际运行 `d7427c2`、`b37ee660` 两个历史实现，
+没有用新代码上的 legacy 开关模拟旧端。
+
+7 项测试覆盖旧 SYN 处理探针和两个基线的新旧双向连接、256 KiB 双向
+数据、半关闭、重复 SYN。报文捕获断言：新源初始 SYN 可为 `rsv=1`，
+其余混合连接报文均为 `rsv=0`；没有 FIN_ACK、新增 RST 或重复 accept。
+
+`d7427c2` 原有正常关闭被报告为 BrokenPipe 的行为仍在对照中保留。
+兼容意味着旧节点仍可互通，不意味着它自动获得新协议的恢复能力。
+
+## 实际代理流量
+
+实验使用独立 namespace，底层 UDP，
+覆盖 TCP/KCP/QUIC 与内核/smoltcp 六种模式。固定每轮 300 次短连接、
+16 并发、5 s socket 超时，逐字节校验大小请求、纯空请求及反向半关闭。
+
+验证分为两个阶段；不将初版流量统计冒充最终版本结果。
+
+### 初版 c84733d
+
+二进制 `protocol-easytier-core` 的 SHA-256 为
+`f41ff98762ed1ce8691d8f83b8c9e47acc4548c76432a17cd2daba36e2cc7b80`。
+
+- 六模式主矩阵：1,800 次短连接、12 次大小请求半关闭、6 次反向
+  半关闭、192 次纯空请求，全部通过。
+- KCP 每栈追加三轮，合并主矩阵共 2,400 次 KCP 短连接，全部通过。
+- `netem delay 10ms 3ms loss 1%` 六模式：1,800 次短连接、12 次大小
+  半关闭、6 次反向、192 次纯空及每组合 15 s 双连接持续流量，全部通过。
+- 新旧双方向各六模式：3,600 次短连接、24 次大小半关闭、384 次纯空
+  和每组合 3 s 持续流量通过；**反向半关闭为 11/12，存在一次失败**。
+
+旧端为依赖 b37 的 `delivery-easytier-core`，SHA-256 为
+`4635810ac9a536258f9b7ff606e5e1a5eb0243cb0f187825ba6f721d92dfc4fe`。
+失败发生在新 source → 旧 destination 的 KCP/smoltcp，连接
+`conv=3560055726`、源端口 `40748`：客户端已经收到完整 1 MiB，随后
+等待 EOF 超过 5 s；因此未进入后发 256 KiB 阶段。旧目标端在
+10:11:08.953 进入 LocalClosed，直到客户端超时才见客户端方向关闭。
+DEBUG 不能确定旧端 FIN 后续的发送、到达或处理点，不能直接定性为
+FIN 丢失，也不能把混合版本测试写成全部通过。
+
+另一次有界 KCP/kernel 丢包 TRACE 测试中，300 次短连接及全部半关闭
+通过。实际捕获的控制事件全部使用 version 1：连接 `1468864199` 的
+重复 SYNACK 相隔约 200 ms，目标随后收到 ACK，业务完成；连接
+`1468864161` 的重复 FIN 后收到 FIN_ACK。它们证明实际链路使用了
+新控制恢复路径；单轮成功不代表任意丢包条件下都能成功。
+
+### 最终 3ef5c416
+
+- 六模式主矩阵全部通过：1,800 次短连接、12 次大小半关闭、6 次反向
+  半关闭、192 次纯空请求。
+- 六模式随机丢包全部通过：相同流量规模，另每组合 15 s 双连接持续
+  逐字节回显。原 5 s socket 超时不变，没有添加应用重试。
+- 混合版本无丢包，两连接方向 × 两个 KCP 栈全部通过：1,200 次短连接、
+  8 次大小半关闭、4 次反向及 128 次纯空请求。该轮通过不覆盖初版
+  混合实验中的 EOF 超时记录。
+- KCP 每栈追加三轮全部通过；合并主矩阵为 **2,400/2,400** 次 KCP
+  短连接；追加轮次的 12 次大小、6 次反向和 192 次纯空也全部通过。
+混合丢包仍走 legacy，下表为单轮**失败数**，不重跑取最好结果。
+每组合为 300 短连接、2 次大小半关闭、1 次反向、32 次纯空和 3 s 持续流量。
+
+| 连接方向/栈 | 短连接失败 | 大小失败 | 反向失败 | 纯空失败 | 持续失败 |
+| --- | --- | --- | --- | --- | --- |
+| b37 → 最终新 / kernel | 6 | 0 | 0 | 16 | 0 |
+| b37 → 最终新 / smoltcp | 2 | 0 | 0 | 13 | 0 |
+| 最终新 → b37 / kernel | 7 | 1 | 0 | 16 | 0 |
+| 最终新 → b37 / smoltcp | 1 | 0 | 0 | 14 | 0 |
+
+唯一大小用例失败停在 greeting 阶段，5 s 超时；纯空失败为 response
+阶段收到空 EOF。为判断兼容回退，另跑一次相同条件、相同业务参数的
+b37 → b37 旧旧对照：kernel 短连接失败 2/300、纯空失败 12/32；
+smoltcp 分别为 0/300、16/32。两栈的大小、反向与持续项目均通过。
+
+旧旧 TRACE 确认了一条失败链：kernel 的 `conv=3046346801`、空请求
+`id=3`、源端口 `35958`，目标在 10:30:44.112 先收到 FIN，直接
+Closed 并发送 RST；10:30:44.115 才收到最终 ACK|DATA。源在 .113
+收到 RST，客户端约 37 ms 后得到零字节 EOF。`src/state.rs` 的
+SynReceived + FIN → Closed/RST 路径本次没有修改；可靠模式单独支持
+FIN 完成握手，legacy 按已批准设计保留原行为。
+
+这条时序证明上述失效路径在旧旧连接也存在，不能由随机样本的失败率
+断言所有混合版本失败均已归因或已经排除一切回退。混合实验原 DEBUG
+不足以逐包归因全部失败。兼容保证旧节点可按原协议互通；控制恢复能力
+需要两端都协商为 version 1，混合部署仍不能获得这一保证。
+
+最终丢包轮次直接启用 KCP TRACE：kernel 捕获 5 个成功连接收到重复
+SYNACK、4 个收到重复 FIN；smoltcp 分别为 2 个、5 个。捕获的控制
+报文均使用 version 1。详见 `final-control-recovery-*-summary.json`
+及对应 `evidence.log`；这份证据直接绑定最终二进制。
+
+资源观察区分应用代理条目与内部 KCP 状态。CLI 不直接暴露依赖内部
+关闭记录，不能用 CLI 条目清零证明内部记录已经删除；内部期限由
+生命周期测试验证。实际流量保存起始、结束、15 s、80 s 的 FD/RSS 与
+应用代理条目。65 s 关闭记录属于设计成本，不能沿用旧的 15 s 内部
+状态必须清零的断言。
+
+最终每栈三轮连续负载的资源结果如下。a 为 source，b 为 destination。
+该追加轮次的 FD 全程未增长；应用 proxy 条目在 15 s 与 80 s 均为零。
+
+| 栈/节点 | FD 前后 | RSS 前 → 80 s（KiB） | 负载 CPU 秒 / 墙钟秒 | 静置 15–80 s 单核 CPU |
+| --- | --- | --- | --- | --- |
+| kernel/a | 15 → 15 | 46,944 → 50,792 | 2.20 / 2.697 | 0.29% |
+| kernel/b | 15 → 15 | 46,580 → 49,344 | 1.12 / 2.694 | 0.31% |
+| smoltcp/a | 14 → 14 | 46,784 → 50,352 | 4.39 / 5.378 | 0.49% |
+| smoltcp/b | 14 → 14 | 46,024 → 49,060 | 2.32 / 5.368 | 0.48% |
+
+CPU 来自 `/proc/PID/stat` 的 user/system ticks 与单调时钟差，包含
+路由、心跳、代理、日志等全部进程工作。产物为 debug 构建，表中负载
+CPU 也不是纯协议开销或吞吐基准。RSS 未回到起点，无法由这些采样区分
+分配器缓存与其他长期对象，也不能推算每条关闭记录的精确内存成本。
+内部对象期限由单测验证，生产规模的逐对象内存与长期容量验证仍未完成。
+主矩阵 kernel/b 在 15 s 采样曾由 15 个 FD 暂升为 16，80 s 恢复为 15；
+该瞬时变化同样保留在原始报告，未作为持续增长处理。
+原始记录为 `final-kcp-repeat-kcp-*-resources.json`，换算另存
+`final-resource-summary.json`。
+
+## 审查、复现与限制
+
+初轮独立子代理只读审查 `b37ee660..c84733d`，没有高置信度缺陷发现。
+最终由新子代理审查完整 `b37ee660..3ef5c416` 及 EasyTier 最终 pin，
+未发现 blocker / major；重点检查旧版输出规则、握手与关闭交叉状态、
+队列、取消清理和锁序。
+
+最终审查记录一项 **minor / high confidence** 待办：
+`kcp-sys/src/endpoint.rs:922` 新 SYN 路径先 notify 再插入连接状态，
+多线程时可能先消费通知并漏过首次 SYNACK 调度。正常源端约 200 ms 后
+重发 SYN 即可恢复；若后续 SYN 未到达，则等待约 10 s 周期扫描。状态
+不会丢失，也不会永久阻塞，但特别短的 connect 期限可能超时。按用户
+minor 默认记录的规则保留；后续最小改动是将通知放到状态插入之后。
+
+主要命令：
+
+```sh
+# kcp-sys 工作树
+cargo test --all-targets
+cargo fmt --all -- --check
+cargo clippy --all-targets -- -D warnings
+
+# EasyTier，Linux root 集成测试在 rust 容器内执行
+cargo +1.95 test --locked -p easytier-core \
+  --features proxy-smoltcp-stack --lib gateway::
+cargo +1.95 nextest run --locked -p easytier --features full --lib \
+  -E 'test(subnet_proxy_three_node_test) | test(subnet_proxy_half_close_test) | test(acl_rule_test_inbound) | test(acl_rule_test_subnet_proxy) | test(proxy_three_node_disconnect_test) | test(config_patch_test) | test(port_forward_with_inbound_default_drop_acl_test)' \
+  --test-threads 1 --no-fail-fast
+cargo +1.95 clippy --locked -p easytier --features full \
+  --lib --tests -- -D warnings
+```
+
+本机原始日志、脚本、JSON 与二进制：
+
+```text
+/data/project/kcp-control-validation-20260914/
+```
+
+主要证据为 `final-ack-red.log`、`final-ack-green.log`、
+`final-dependency-tests.log`、`final-dependency-clippy.log`、
+`unknown-close-full-output-red.log`、`legacy-final.log`、
+`negotiation-lifetime-regressions.log`、`final-native-*-tests.log`、
+`linux-gateway.log`、`integration-final.log`、`app-final-clippy.log`。
+`integration-protocol.log` 是初版的中断轮次，切换最终实现后重新执行完整
+矩阵，不计入最终通过数。
+流量的准确 argv、产物 hash 和逐连接结果另存该目录。完整流量汇总为
+`traffic-summary.md`，混合丢包对照为 `mixed-loss-analysis.md`，
+旧旧逐包证据为 `legacy-fin-before-ack-evidence.log` 与
+`legacy-fin-before-ack-client.json`。测试环境清理记录为 `cleanup.json`。
+
+此前单次反向超时的具体丢包点仍不能由旧 DEBUG 日志倒推出。定点 FIN
+丢失测试证明该类失效现在能够恢复，不能因此改写原事故的根因结论。
+Windows/macOS 原生 TUN 端到端、生产规模长期负载、吞吐与容量上限仍
+不是这些有限测试能够证明的事项。

docs/socket-protection.md

@@ -0,0 +1,84 @@
+# Host socket protection
+
+VPN bypass is a socket-creation requirement, not an operation on a socket that
+core has already connected. Core and WASI guests never need an OS file descriptor.
+
+## Portable requests
+
+`TcpBindOptions::need_protect` and `UdpBindOptions::need_protect` travel through the
+existing connect/bind operations. A host requiring VPN bypass must acknowledge
+successful protection before connect, bind/listen, or publishing the socket.
+Failure or cancellation fails creation and discards the owned socket; emitting
+an event alone is not acknowledgement. Platforms without VPN bypass can treat
+the requirement as a no-op.
+
+- TCP connect constructors request protection, including egress for proxies.
+- TCP transport/hole-punch listeners request protection. Hosts retain this flag
+  on the listener and protect accepted children before handing them to core.
+- Local ProxyNat/SOCKS/port-forward/port-lease listeners do not request it.
+- UDP transport, candidates, listeners, NAT egress and STUN request protection;
+  HolePunchControl, local SOCKS/port-forward and port-lease sockets do not.
+- Low-level TCP/UDP bind options default to protection, including deserialization
+  of options without `need_protect`. The named local/TUN-facing constructors set
+  `false` explicitly. The UDP default keeps its historical purpose label for
+  socket setup; only the named `hole_punch_control()` constructor opts out.
+- `with_bind()` replaces the **entire** bind object. A local listener's replacement
+  must retain its opt-out rather than inherit the protected default. A native
+  adapter must honor explicit `false`, not silently change it based on `purpose`.
+- DNS and source-route queries are already host-owned operations. A bypass-enabled
+  host must protect their underlying sockets before querying/probing, including
+  DNS TCP fallback, rather than letting system DNS silently bypass this contract.
+
+## TUN-facing ingress and port forwarding
+
+The extra `force_smoltcp` wildcard port-forward ingress listener has been removed.
+Normal TUN-backed ingress is delivered to the existing unprotected native listener;
+its accepted sockets remain unprotected so overlay replies can return through TUN.
+The physical/underlay egress socket is protected independently. A separate
+DataPlane listener must not mask broken host/TUN routing in this path.
+
+This does not remove the existing public DataPlane listener APIs, the generic
+no-TUN smoltcp TCP proxy, or `force_smoltcp` itself. Those have other uses. Whether
+Android subnet proxy works without forced smoltcp needs actual platform regression
+testing; socket-creation unit tests alone do not establish that result.
+
+## Native integration and HarmonyOS
+
+The native `easytier` adapter implements the creation requirement using an async
+`NativeSocketProtector` callback. This is a native implementation detail, not a
+new portable or WASI ABI. It takes only the native handle; the creation options
+select policy, without a second purpose enum. Namespace switching is confined to synchronous socket
+creation and never held across the callback's await.
+
+The existing native `bind` builder is async and shared by TCP/UDP creation. Its
+legacy direct-call default remains unprotected; portable factories explicitly
+pass their core bind options (default protected). Callers must await `.call()`.
+TCP listeners reuse TCP socket creation then listen, instead of duplicating the
+setup. Existing legacy WebSocket direct-call policy is unchanged.
+
+The HarmonyOS broker wakes the already-pending request consumer with `Notify`
+(no polling timer). It keeps a duplicate FD alive until ArkTS completes
+`VpnConnection.protect(fd)` and returns its ACK. The waiting creation future is
+woken immediately by the oneshot acknowledgement. Failure stays fail-closed;
+shutdown retains dispatched FDs for late ACKs to prevent FD reuse races.
+The ArkTS request shape is unchanged; its diagnostic `purpose` string is now
+the generic `"socket"`. Neither ACK routing nor protection policy uses that label.
+
+This guarantees ordering, not a wall-clock real-time bound: OS/ArkTS scheduling
+can still delay protection. Such a delay keeps the socket unconnected; it must
+never allow the first SYN/query to race ahead of protection.
+
+## WASI option format
+
+The `easytier_host` import names and function signatures are unchanged. TCP
+connect, TCP listen and UDP bind use option document **version 3** (previously 2):
+one `u8` boolean `need_protect` is inserted immediately after the existing purpose
+byte and before the optional bind-device field. All other field encodings and
+purpose values are unchanged. The document version lets older hosts reject
+unsupported options instead of silently ignoring protection. DNS, environment,
+instance-config and data-plane layouts/versions are unchanged.
+
+An embedding host must update its versioned option decoder and honor the flag
+inside its existing creation implementation. The external host implementation
+is not in this repository: building the guest proves propagation/compatibility
+of imports, not that every external host has implemented platform protection.

docs/tcp-proxy-flow-key-validation-2026-09-13.md

@@ -0,0 +1,137 @@
+# TCP proxy flow-key 验证记录（2026-09-13）
+
+本次验证没有发现只在修复版本出现的行为退化。同源端口、不同目标的
+并发连接在六种代理模式下均由父提交的超时变为成功。验证中仍有半关闭
+失败和 KCP 突发短连接超时，父提交也存在这些现象，不能将结果描述为
+所有场景均无异常。
+
+## 版本与范围
+
+- 修复版本：`eb83655958be932d6de34e090dc361b6f3ba3393`。
+- 父提交：`e0bdb516b6dc8a654940efbe12960dbfa846f424`。
+- 本次提交仅新增测试与记录，生产代码保持上述修复版本的内容。
+- Linux 测试在现有 `rust` 容器内运行，Rust 1.93.1。
+- macOS arm64、Windows x64 原生测试使用 Rust 1.95.0。
+
+父提交使用独立 worktree，但复用当前 worktree 的 `target`。第一次父提交
+网关测试意外复用了修复版本的构建缓存，结果已排除。清理相应 package
+的构建产物后重新编译，确认父提交网关测试为 189 项，修复版本原有
+192 项。真实流量实验还通过 CLI 核对两端实际运行的版本号。
+
+## 自动化验证
+
+| 验证 | 结果 |
+| --- | --- |
+| 修复版本完整 `subnet_proxy_three_node_test` 矩阵 | 256/256，714.800 秒 |
+| ACL、端口转发 ACL、配置更新、代理断连 | 父提交与修复版本各 14/14 |
+| 父提交 Linux 网关测试 | 189/189 |
+| 新增测试后的 Linux 网关测试 | 198/198 |
+| 新增测试后的 macOS 原生网关测试 | 198/198 |
+| 新增测试后的 Windows 原生网关测试 | 198/198 |
+
+完整三节点矩阵覆盖 TUN/no-TUN、普通/公共中继、源端 KCP/QUIC 开关、
+目标端 KCP/QUIC 开关及对应输入禁用组合。每个组合检查映射子网地址、
+真实子网地址和节点虚拟地址上的 ICMP、TCP、UDP。
+
+命令（Linux 需在容器内运行）：
+
+```sh
+cargo nextest run -p easytier --features full --lib \
+  subnet_proxy_three_node_test --test-threads 1 --no-fail-fast
+
+cargo test -p easytier-core --features proxy-smoltcp-stack --lib gateway::
+
+cargo fmt --all -- --check
+
+cargo clippy -p easytier-core \
+  --features proxy-smoltcp-stack,ring-crypto --lib --tests -- -D warnings
+```
+
+格式检查和上述严格 Clippy 检查均通过。仅启用 `proxy-smoltcp-stack`
+时，严格 Clippy 被未修改的 `tunnel/encrypt/mod.rs` 中
+`assert_interoperable` 未使用警告阻断；增加 `ring-crypto` 会启用调用
+该函数的现有后端互操作测试。本次没有修改或屏蔽该警告。
+
+14 项补充集成测试来自以下测试组，使用各版本独立保存的测试二进制，
+逐项 `--exact` 执行，避免不同进程同时操作相同的测试 network namespace：
+
+- `acl_rule_test_inbound`：4 项。
+- `acl_rule_test_subnet_proxy`：4 项。
+- `port_forward_with_inbound_default_drop_acl_test`：3 项。
+- `config_patch_test`：1 项。
+- `proxy_three_node_disconnect_test`：2 项。
+
+三节点矩阵与流量实验在新增测试前完成；新增测试不改变生产代码，随后
+在三平台重新执行完整网关测试。macOS、Windows 的结果不包含原生 TUN
+端到端验证。
+
+## 新增回归测试
+
+测试位于 `easytier-core/src/gateway/proxy/tcp_proxy_engine.rs`：
+
+1. SYN 在 accept 前后重传，均保留转换端口，且不会重复 accept。
+2. 旧连接处于 ClosingSrc、ClosingDst、Closed 时，被同一流的新连接
+   替换；旧连接清理不会删除新映射，反向地址、端口和校验和仍正确。
+3. 过期 SYN 同时释放两个索引，已 accept 的连接不受 SYN 超时清理影响。
+4. 转换端口计数器回绕后跳过零、已占用端口和监听端口。
+5. 实际填满同一源 IP 的 65,534 个转换端口后，新 SYN 被丢弃；其他源
+   IP 仍可建立映射，释放一个条目后该端口可复用，clear 后也可重新分配。
+6. 八个线程同时处理同一流，仅建立一个映射并成功 accept 一次。
+
+端口池测试验证实际容量和恢复行为，没有将 debug 构建的耗时用作生产
+性能阈值，也没有通过延长超时或添加重试改变被测行为。
+
+## 真实流量对照
+
+使用独立的 `flow_val_a`、`flow_val_b` namespace，物理链路为一对 veth。
+虚拟地址为 `10.251.92.1/24` 和 `10.251.92.2/24`；目标端将
+`192.0.2.0/24` 映射到 `198.18.0.0/24`。两个 TCP 服务监听真实地址
+`.10`、`.11` 的 23456 端口，返回服务地址标记，并逐字节回显、校验数据。
+底层隧道使用 UDP，两个节点均使用四线程运行时。
+
+每个版本分别验证普通 TCP、KCP、QUIC 与内核/smoltcp 的六种组合。
+
+| 场景 | 父提交 | 修复版本 |
+| --- | --- | --- |
+| 源 IP/端口相同、两个不同目标的并发连接，各进行 30 轮回显 | 6/6 超时 | 6/6 通过 |
+| 同一四元组 RST 后重连，30 次，间隔 20ms | 6/6 通过 | 6/6 通过 |
+| 普通 TCP、QUIC 的短连接，各 300 次、16 并发 | 各组合 300/300 | 各组合 300/300 |
+| KCP 内核模式短连接，300 次、16 并发 | 4 次超时 | 4 次超时 |
+| KCP smoltcp 模式短连接，300 次、16 并发 | 12 次超时 | 11 次超时 |
+| 关闭客户端写端后等待服务端响应 | 6/6 无响应数据 | 6/6 无响应数据 |
+
+各组合完成流量后等待 15 秒。修复版本两端的代理条目均回收为零，FD
+数量回到接近起始水平（采样期间 RPC 连接带来约一个 FD 的差异）。这只能
+证明本次有限负载下的回收行为，不能证明长期内存占用没有增长。
+
+KCP 的超时阈值为 5 秒，尚未定位这些突发短连接超时的根因；两版都有
+失败不等于已证明每次失败属于同一根因。半关闭实验的服务端在 EOF 后
+返回响应；未修改的 `copy_bidirectional_no_shutdown` 在任一方向结束
+后即退出转发，与两版都丢失该响应的现象一致。本次不修复这两类问题。
+
+## 丢包与混合版本
+
+- 在客户端 veth 出方向施加 `netem delay 10ms 3ms loss 1%`。
+- 两版各六种模式，每个组合保持两个连接持续回显至少 15 秒，所有数据
+  均通过逐字节校验；共 12/12 通过。
+- 无 netem 时，旧源端/新目标端、新源端/旧目标端，各覆盖六种模式。
+  两个连接持续回显至少 2 秒，共 12/12 通过。
+- 混合版本验证使用不同客户端源端口，验证正常互通；它不意味着仍运行
+  旧代理引擎的一端也获得了同源端口冲突修复。
+
+## 证据与限制
+
+本机原始日志、流量脚本、各阶段 JSON、二进制与 SHA-256 清单保存在：
+
+```text
+/data/project/tcp-flow-validation-20260913/
+```
+
+主要记录为 `manifest.json`、`current-matrix-summary.log`、
+`*-extra.json`、`traffic-matrix.json`、`loss-interop.json` 和
+`current-final*gateway.log`。矩阵记录是最终摘要，不是完整逐项日志。
+实验进程、独立 namespace 和 netem 均已清理。
+
+未覆盖 Windows/macOS 原生 TUN 路径、生产防火墙/conntrack 规则兼容性、
+长期运行、吞吐回归基准，以及接近容量极限时的真实内核连接负载。
+端口耗尽已在引擎级验证，但不能替代上述生产容量测试。

docs/tcp-proxy-half-close-validation-2026-09-14.md

@@ -0,0 +1,178 @@
+# TCP 代理半关闭与 KCP 短连接修复验证（2026-09-14）
+
+本次修复上一轮验证发现的半关闭失败、无丢包 KCP 突发连接交接丢失，
+以及跨平台验证暴露的握手前心跳竞态。这些是转发与连接生命周期的局部
+逻辑问题；没有改变 KCP 报文格式，也没有增加重试或放宽业务超时。
+丢包网络下另有握手最终 ACK 丢失的问题，本次未修复，见下文。
+
+## 版本与根因
+
+- EasyTier 基线：`24572b49`；生产修复：`03fa375e`、`fd6e2a3e`。
+- kcp-sys 基线：`d7427c22d764deb1860a7d37acc446ed5033464c`。
+- 最终依赖：`b37ee660fb70bb6d816fb8bbc08b140e55e7218b`，
+  `Cargo.toml` 和 `Cargo.lock` 均锁定此 Git revision。
+  已发布到 kcp-sys 的 `fix/accept-half-close-20260914` 专用分支，
+  便于其他机器获取锁定的依赖；未合并主分支。
+- 旧版真实流量对照：`eb836559`，已包含 flow-key 修复，尚无本次修复。
+- 最终流量二进制：`delivery-easytier-core`，SHA-256：
+  `4635810ac9a536258f9b7ff606e5e1a5eb0243cb0f187825ba6f721d92dfc4fe`。
+  构建内容与最终生产代码一致；构建发生在依赖 pin 提交前，内嵌版本号
+  不用于区分本次产物，以 SHA-256 和依赖 revision 为准。
+
+修复内容：
+
+1. 原转发函数在任一方向 EOF 后退出，取消另一方向，服务端在请求 EOF
+   后返回的响应因此丢失。改用 Tokio 双向拷贝传播写端关闭，继续转发
+   反向数据，直到双向完成或发生错误。
+2. KCP 容量为 4 的 accept 通知队列满时，已建立连接失去交接机会。
+   在连接状态中保留待 accept 标记，队列为空时领取待交接连接；保留
+   原有有界通知队列和串行领取，防止重复交接。
+3. KCP 将正常关闭当作读错误，并可能在 FIN 后丢弃已经确认接收、尚未
+   交给应用的数据。现在先排空接收数据再返回 EOF，RST 和端点销毁仍
+   返回错误；双向关闭清理等待接收任务完成。EOF 判断和过期清理的
+   状态读取顺序也一并修正，避免并发数据到达或心跳更新被旧判断覆盖。
+4. FIN 可以先于 accept 或 connect 返回到达。创建流时继承该关闭状态，
+   使纯空请求、纯空响应也能得到 EOF。半关闭连接继续响应心跳。
+5. Windows 原生测试捕获到 PING 先于 SYN 到达，对端因连接未知返回
+   RST；旧依赖也复现相同时序。周期心跳现在只覆盖已建立和半关闭状态。
+
+## 回归覆盖与自动化结果
+
+| 验证 | 结果 |
+| --- | --- |
+| Linux、macOS arm64、Windows x64 原生网关测试 | 各 200/200 |
+| 最终 kcp-sys 三平台原生测试 | 各 10/10，两个 example target 通过 |
+| 最终完整三节点矩阵及补充集成测试 | 276/276，848.628 秒 |
+| EasyTier 格式检查、Linux 严格 Clippy | 通过 |
+| kcp-sys Linux/macOS 格式检查、严格 Clippy | 通过 |
+
+网关新增两个测试，分别从两端先关闭写方向；使用空请求、32 KiB 请求
+及 64 KiB 响应，接收方等到 EOF 才返回响应。旧转发函数两项均在 5 秒
+超时，修复后通过。原生网关测试不依赖应用层 KCP，心跳修复没有改变
+这些测试的生产代码。
+
+新增三节点半关闭测试覆盖 TCP/KCP/QUIC × 内核/smoltcp 六种模式，
+各检查两个关闭方向、空请求和 64 KiB 请求、128 KiB 响应。完整集成
+集合共 276 项：原有三节点矩阵 256 项、新增 6 项、ACL/配置更新/
+端口转发/断连 14 项，均在已有 `rust` 容器中串行运行。
+
+依赖回归覆盖：32 次握手全部完成后才 accept；200 KiB 缓冲数据后的
+EOF/响应；双向关闭后跨越清理周期再读数据；半关闭心跳；RST/端点销毁
+读错误；FIN 先于 accept、FIN 先于 connect 返回；各握手阶段的心跳
+筛选。通知饱和测试在旧实现第五次 accept 超时；提前 FIN 测试在修复
+前等待 EOF 超时。排空测试使用多工作线程运行时，并做过额外重复验证。
+
+主要命令（Linux 容器内，Rust 1.95）：
+
+```sh
+cargo +1.95 test --locked -p easytier-core \
+  --features proxy-smoltcp-stack --lib gateway::
+cargo +1.95 nextest run --locked -p easytier --features full --lib \
+  -E 'test(subnet_proxy_three_node_test) | test(subnet_proxy_half_close_test) | test(acl_rule_test_inbound) | test(acl_rule_test_subnet_proxy) | test(proxy_three_node_disconnect_test) | test(config_patch_test) | test(port_forward_with_inbound_default_drop_acl_test)' \
+  --test-threads 1 --no-fail-fast
+cargo fmt --all -- --check
+cargo +1.95 clippy --locked -p easytier --features full \
+  --lib --tests -- -D warnings
+```
+
+网关严格 Clippy 另以 `proxy-smoltcp-stack,ring-crypto` 通过；原因见上一轮
+记录中的既有未使用警告说明。Windows 所选 stable 工具链缺少格式检查
+组件，未将 Windows 格式或 Clippy 计为通过。
+
+## 最终二进制真实流量
+
+普通 TCP、KCP、QUIC 与内核/smoltcp 六种组合，底层 UDP；每组合 300 次
+短连接、16 并发、5 秒 socket 超时，检查 greeting 和逐字节回显。
+
+- 六模式主矩阵：1,800/1,800 次短连接通过。
+- 请求 EOF 后返回响应：小/大请求共 12/12，通过；大请求 256 KiB，
+  响应 1 MiB + 4 字节。
+- 服务端先关闭写端，客户端读到 EOF 后再发 256 KiB：6/6，通过，
+  服务端实际校验接收数据。
+- connect 后立即关闭写端，不发送模式字节、不等待 greeting：每模式
+  32 次、16 并发，共 192/192 次纯空请求通过。
+- KCP 每栈额外三轮，与主矩阵合计 2,400/2,400 次短连接通过。追加
+  测试的大小半关闭及 192 次纯空请求通过，6 次反向半关闭中 1 次超时，
+  因此不能将所有追加半关闭计为通过，具体证据见下文。
+- 最终版本在 `delay 10ms 3ms loss 1%` 下，六模式各两个连接持续
+  15 秒逐字节回显、12 次大小半关闭及 6 次反向半关闭通过。KCP 短连接
+  仍有内核模式 5/300、smoltcp 模式 8/300 次 greeting 超时，其他
+  四种模式零失败；没有为每次超时单独抓包证明原因相同。
+- 新旧两方向 × 六模式，共 12 组合正常持续回显通过。旧源端→新目标端
+  1,800 次短连接全通过；新源端→旧目标端 KCP 内核模式 12/300、
+  smoltcp 模式 9/300 次超时，其他四种模式零失败。
+
+旧版同样的无丢包 KCP 2,400 次短连接有 78 次 greeting 超时；旧版六种
+模式在请求 EOF 后均没有响应，且出现过 QUIC 请求数据被截断。
+
+最终版本 KCP 主矩阵后，两种栈源端各 335 条 Closed 代理记录均在
+15 秒观察点清零；目标端记录为零。两端 FD 数保持内核模式 15、smoltcp
+模式 14。RSS 较起始保留约 3.2–4.4 MiB 增长，单次有限负载不能证明
+或排除长期内存泄漏，也不能将代理条目清零等同于所有内部对象回收。
+
+## 仍然存在的丢包握手问题与升级限制
+
+在源端施加 `netem delay 10ms 3ms loss 1%` 后，中间修复版本
+（SHA-256 `2e78ecf…`）KCP 仍有 3/600 次 greeting 超时。额外有界
+TRACE 重跑捕获 3 个连接：源端收到 SYN|ACK，发出空 ACK|DATA 后即
+返回已建立；目标端未收到最终 ACK，直到 5 秒后的 FIN 才返回 RST。
+这与 accept 通知饱和不同，目标端尚未完成握手。
+
+该控制报文可靠性问题需要单独设计握手恢复、重传及过期清理的一致性，
+不能仅延长超时或重试应用请求。本次没有声称消除了所有 KCP 超时。
+具体连接号和双方日志行见 `remaining-loss-handshake.md`、
+`loss-handshake-evidence.log`。
+
+混合版本正常回显通过并不意味着旧端获得修复。旧 KCP 目标端仍保留
+accept 缺陷；KCP 的完整半关闭能力需要两端升级。没有修改报文格式。
+
+追加无 netem 的 KCP/kernel 反向半关闭中，连接 `3969305677` 在等
+服务端数据和 EOF 时超时；服务端没有收到客户端原定在 EOF 后发送的
+256 KiB 数据。发送端同一连接出现 780 次数据输出队列 Full，随后在
+08:36:47.247 UTC 发送缓冲排空，FIN 成功进入输出队列；接收端直到
+5 秒业务超时都未报告对端关闭，08:37:01.030 才报告关闭或重置信号。
+该 debug 日志行也可能由 RST 触发，不能据此认定迟到的是 FIN，更不能
+将数据队列 Full 直接解释为 FIN 被该队列丢弃。现有 FIN 发送路径没有
+确认重传；这一单次失败的具体丢包点尚未证实，保留为未解决的验证异常。
+同场景有界 TRACE 重跑 3 轮，900 次短连接、3 次反向半关闭均通过，
+抓包确认成功轮次收到 FIN 并完成反向数据，未复现原失败；不能以重跑
+通过覆盖原失败。旧依赖与最终依赖的发送排空后入队 FIN 路径相同，
+对照保存在 `fin-send-path-old-new.txt`。
+
+异常轮次的 15 秒资源观察点仍有 1 条 Closed 代理记录，无 Connecting/
+Connected，FD 已回到起始值；因此仅主矩阵可以报告该观察点全部清零。
+定向 TRACE 三轮的 1,005 条 Closed 记录在 15 秒观察点全部清零。
+
+## 验证中的异常与证据
+
+首轮未完成的集成运行中，端口转发 ACL case 3 曾在连接本地监听端口时
+出现一次 ConnectionRefused；随后完整一轮 276 项通过，同项也通过。
+旧版单次及额外十次均通过，因此没有证据把这次失败断言为旧版必现问题，
+也未修改无关的端口转发代码。新增半关闭测试的早期夹具曾只等待路由
+公告而未等待实际 TUN 路由可用，已补足就绪检查，并用有界 try_join
+及时报告连接错误；这不计入生产代码的 red/green 对照。
+
+Windows 测试早期表现为挂起，原因是测试 join 在 connect 失败后仍等待
+accept。限定握手等待后暴露出上述 PING/RST/SYN 竞态，旧依赖和修复前
+分支均有 TRACE 证据；最终原生测试通过。完整 diff 和后续心跳增量均
+经过独立子代理审查，没有 high-confidence 的新缺陷发现。
+
+原始脚本、日志、逐连接 JSON、二进制和哈希保存在本机：
+
+```text
+/data/project/proxy-close-validation-20260914/
+```
+
+主要文件：`delivery-manifest.json`、`delivery-integration.log`、`delivery-clippy.log`、
+`final-core-gateway.log`、`macos-core.log`、`windows-core.log`、
+`mac-kcp-heartbeat-tests.log`、`final-tests.log`（Windows KCP）、
+`delivery-summary.json`、`delivery-kcp-repeat-summary.json`、
+`delivery-*-resources.json`、`traffic-summary.md`、`traffic-binaries.json`、
+`delivery-commands.json`、`artifacts-manifest.json`、`delivery-reverse-timeout.md`、
+`relay-red.log`、`windows-kcp-trace-fail.txt`、
+`windows-kcp-baseline-startup.txt`。Windows 部分原始日志为 UTF-16LE。
+Linux kcp-sys 测试、格式、Clippy 及依赖测试 red/green 对照为子代理
+执行结果，未单独落盘原始命令日志；最终 10 项测试耗时 11.03 秒。
+
+未覆盖 Windows/macOS 原生 TUN 端到端路径、生产规模长时间运行、吞吐
+基准及容量极限负载。流量实验仅使用并清理自己的 namespace 和进程。

easytier-contrib/easytier-android-jni/Cargo.toml

@@ -7,11 +7,11 @@ edition.workspace = true
 crate-type = ["cdylib"]
 
 [dependencies]
-jni = "0.21"
-once_cell = "1.18.0"
-log = "0.4"
-android_logger = "0.13"
-serde = { version = "1.0.220", features = ["derive"] }
-serde_json = "1.0"
-easytier = { path = "../../easytier" }
-easytier-ffi = { path = "../easytier-ffi", default-features = false }
+# JNI 0.22 changes native entry points to EnvUnowned and Env.
+jni = "0.21.1"
+once_cell.workspace = true
+log.workspace = true
+android_logger = "0.15"
+serde_json.workspace = true
+easytier = { workspace = true, default-features = true }
+easytier-ffi.workspace = true

easytier-contrib/easytier-ffi/Cargo.toml

@@ -15,20 +15,24 @@ ffi-dataplane = [
 ]
 
 [dependencies]
-easytier = { path = "../../easytier", features = ["tracing-log"] }
-easytier-core = { path = "../../easytier-core" }
+easytier = { workspace = true, default-features = true, features = ["tracing-log"] }
+easytier-core = { workspace = true, default-features = true }
 
-once_cell = "1.18.0"
-tokio = { version = "1", features = ["rt-multi-thread", "io-util", "time", "sync", "macros"] }
-async-trait = "0.1"
-log = "0.4"
+once_cell.workspace = true
+tokio = { workspace = true, default-features = true, features = ["rt-multi-thread", "io-util", "time", "sync", "macros"] }
+async-trait.workspace = true
+log.workspace = true
 
-serde = { version = "1.0", features = ["derive"] }
-serde_json = "1"
-uuid = "1.17.0"
+serde_json.workspace = true
+uuid.workspace = true
 
 [build-dependencies]
-thunk-rs = { git = "https://github.com/easytier/thunk.git", default-features = false, features = [
+thunk-rs = { workspace = true, features = [
     "win7",
 ] }
 
+[package.metadata.cargo-machete]
+ignored = [
+    # Windows-only build.rs setup calls thunk::thunk().
+    "thunk-rs",
+]

easytier-contrib/easytier-ios/Cargo.toml

@@ -7,18 +7,17 @@ edition.workspace = true
 crate-type = ["staticlib", "rlib"]
 
 [dependencies]
-serde_json = "1.0"
-tracing = "0.1"
-tracing-subscriber = { version = "0.3", features = ["env-filter"] }
-easytier-ffi = { path = "../easytier-ffi", default-features = false, features = [
+serde_json.workspace = true
+tracing.workspace = true
+tracing-subscriber = { workspace = true, default-features = true, features = ["env-filter"] }
+easytier-ffi = { workspace = true, features = [
     "c-abi",
 ] }
 
 [dev-dependencies]
-uuid = "1"
-tokio = { version = "1", features = ["io-util"] }
-easytier-core = { path = "../../easytier-core" }
-easytier-ffi = { path = "../easytier-ffi", default-features = false, features = [
+uuid.workspace = true
+easytier-core = { workspace = true, default-features = true }
+easytier-ffi = { workspace = true, features = [
     "c-abi",
     "ffi-dataplane",
 ] }

easytier-contrib/easytier-magisk/README.md

@@ -1,6 +1,23 @@
-# easytier_magisk版模块
-magisk安装后重启
+# EasyTier Magisk 模块
 
-目录位置:/data/adb/modules/easytier_magisk
-配置文件位置://data/adb/modules/easytier_magisk/config/config.toml
-修改config.conf即可，修改后配置文件后去magisk app重新开关模块即可生效
+安装模块并重启后，EasyTier 会读取
+`/data/adb/modules/easytier_magisk/config/config.toml` 启动。
+
+## WebUI
+
+KernelSU 及支持模块 WebUI 的分支管理器可直接从模块详情页打开配置
+界面。Magisk 用户可安装兼容 KernelSU 模块 WebUI 的独立管理器后打开。
+
+WebUI 使用 EasyTier 自身的配置模型加载和校验配置。点击“保存并重启”后，
+模块会先验证配置，原子替换 `config.toml`，再重启正在运行的 EasyTier
+进程。校验失败时原配置保持不变。
+
+如果 `config/command_args` 存在，模块处于启动参数模式并会忽略
+`config.toml`。WebUI 会显示提示并禁止保存；删除 `command_args` 后即可
+使用 WebUI 管理配置。
+
+## 手动配置
+
+也可以直接编辑
+`/data/adb/modules/easytier_magisk/config/config.toml`。保存后在模块管理器中
+禁用 EasyTier，等待 10 秒后重新启用即可让配置生效。

easytier-contrib/easytier-magisk/build.sh

@@ -1,25 +1,32 @@
 #!/bin/sh
+WEBUI_SOURCE="../../easytier-web/config-generator/dist"
 
-version=$(cat module.prop | grep 'version=' | awk -F '=' '{print $2}' | sed 's/ (.*//')
+if [ -f "${WEBUI_SOURCE}/index.html" ]; then
+    rm -rf ./webroot
+    mkdir -p ./webroot
+    cp -R "${WEBUI_SOURCE}/." ./webroot/
+elif [ ! -f "./webroot/index.html" ]; then
+    echo "Error: WebUI 构建产物不存在，请先运行 pnpm --dir ../../easytier-web/config-generator build."
+    exit 1
+fi
 
-version='v'$(grep '^version =' ../../easytier/Cargo.toml | cut -d '"' -f 2)
+version=$(grep '^version =' ../../easytier/Cargo.toml | cut -d '"' -f 2)
 
 if [ -z "$version" ]; then
     echo "Error: 版本号不存在."
     exit 1
 fi
+version="v${version}"
 
 filename="easytier_magisk_${version}.zip"
-echo $version  
+echo "${version}"
 
-
-if [ -f "./easytier-core" ] && [ -f "./easytier-cli" ] && [ -f "./easytier-web" ]; then
-    zip -r -o -X "$filename" ./ -x '.git/*' -x '.github/*' -x 'folder/*' -x 'build.sh' -x 'magisk_update.json'
-else
-    wget -O "easytier_last.zip" https://github.com/EasyTier/EasyTier/releases/download/"$version"/easytier-linux-aarch64-"$version".zip
+if [ ! -f "./easytier-core" ] || [ ! -f "./easytier-cli" ] || [ ! -f "./easytier-web" ]; then
+    wget -O "easytier_last.zip" "https://github.com/EasyTier/EasyTier/releases/download/${version}/easytier-linux-aarch64-${version}.zip"
     unzip -o easytier_last.zip -d ./
     mv ./easytier-linux-aarch64/* ./
     rm -rf ./easytier_last.zip
     rm -rf ./easytier-linux-aarch64
-    zip -r -o -X "$filename" ./ -x '.git/*' -x '.github/*' -x 'folder/*' -x 'build.sh' -x 'magisk_update.json'
-fi
+fi
+
+zip -r -o -X "${filename}" ./ -x '.git/*' -x '.github/*' -x 'folder/*' -x 'build.sh' -x 'magisk_update.json'

easytier-contrib/easytier-magisk/config/config.toml

@@ -16,7 +16,7 @@ rpc_portal = "0.0.0.0:15888"
 network_name = "default"
 network_secret = ""
 
-[[peer]]
+#[[peer]]
 #uri = "协议://中转ip:端口"
 
 [flags]
@@ -29,7 +29,7 @@ latency_first = false
 enable_exit_node = false
 no_tun = false
 use_smoltcp = false
-foreign_network_whitelist = "*"
+relay_network_whitelist = "*"
 disable_p2p = false
 relay_all_peer_rpc = false
 disable_udp_hole_punching = false

easytier-contrib/easytier-magisk/customize.sh

@@ -11,6 +11,7 @@ ui_print "EasyTier 安装位置：/data/adb/modules/easytier_magisk"
 ui_print "配置文件位置：/data/adb/modules/easytier_magisk/config/config.toml"
 ui_print "如需使用启动参数模式，请将 /data/adb/modules/easytier_magisk/config/command_args_sample 重命名为 command_args，并修改其中的内容"
 ui_print "config 目录中存在 command_args 文件时，模块会自动忽略 config.toml 文件"
+ui_print "支持模块 WebUI 的管理器可直接打开配置界面；Magisk 用户可配合 KsuWebUI 使用"
 ui_print "----------------------------------"
 ui_print "注意！启动参数文件中不能存在 \" 和 '，配置文件则没有这个限制"
 ui_print "----------------------------------"

easytier-contrib/easytier-magisk/module.prop

@@ -1,6 +1,6 @@
 id=easytier_magisk
 name=EasyTier_Magisk
-version=v2.6.4
+version=v2.7.0
 versionCode=1
 author=EasyTier
 description=easytier magisk module @EasyTier(https://github.com/EasyTier/EasyTier)

easytier-contrib/easytier-magisk/webui.sh

@@ -0,0 +1,77 @@
+#!/system/bin/sh
+
+MODDIR=$(CDPATH= cd "${0%/*}" 2>/dev/null && pwd -P) || {
+    echo "Failed to resolve module directory" >&2
+    exit 1
+}
+CONFIG_FILE="${MODDIR}/config/config.toml"
+COMMAND_ARGS="${MODDIR}/config/command_args"
+EASYTIER="${MODDIR}/easytier-core"
+
+fail() {
+    echo "$1" >&2
+    exit 1
+}
+
+running_pids() {
+    for process_dir in /proc/[0-9]*; do
+        [ "$(readlink "${process_dir}/exe" 2>/dev/null)" = "${EASYTIER}" ] || continue
+        printf '%s\n' "${process_dir#/proc/}"
+    done
+}
+
+is_running() {
+    [ -n "$(running_pids)" ]
+}
+
+case "$1" in
+    status)
+        if is_running; then
+            echo "running"
+        else
+            echo "stopped"
+        fi
+        ;;
+    config-mode)
+        if [ -f "${COMMAND_ARGS}" ]; then
+            echo "command-args"
+        else
+            echo "toml"
+        fi
+        ;;
+    read-config)
+        [ -f "${CONFIG_FILE}" ] || fail "Configuration file not found: ${CONFIG_FILE}"
+        cat "${CONFIG_FILE}"
+        ;;
+    save-and-restart)
+        [ -f "${COMMAND_ARGS}" ] && fail "command_args is active; config.toml would be ignored"
+        [ -n "$2" ] || fail "Missing base64-encoded configuration"
+        [ -x "${EASYTIER}" ] || fail "easytier-core is not executable"
+
+        TEMP_FILE="${CONFIG_FILE}.webui.$$"
+        trap 'rm -f "${TEMP_FILE}"' EXIT HUP INT TERM
+        umask 077
+
+        printf '%s' "$2" | base64 -d > "${TEMP_FILE}" \
+            || fail "Failed to decode configuration"
+
+        VALIDATION_OUTPUT=$("${EASYTIER}" --check-config -c "${TEMP_FILE}" 2>&1)
+        if [ $? -ne 0 ]; then
+            fail "${VALIDATION_OUTPUT:-Configuration validation failed}"
+        fi
+
+        chmod 0644 "${TEMP_FILE}"
+        mv -f "${TEMP_FILE}" "${CONFIG_FILE}" \
+            || fail "Failed to replace configuration"
+        trap - EXIT HUP INT TERM
+
+        RUNNING_PIDS=$(running_pids)
+        for pid in ${RUNNING_PIDS}; do
+            kill "${pid}" || fail "Failed to restart EasyTier"
+        done
+        echo "saved"
+        ;;
+    *)
+        fail "Usage: $0 {status|config-mode|read-config|save-and-restart BASE64}"
+        ;;
+esac

easytier-contrib/easytier-mini/Cargo.toml

@@ -1,15 +1,15 @@
 [package]
 name = "easytier-mini"
 description = "Minimal native EasyTier node with TCP/UDP tunnels, TUN and UDP hole punching."
-version = "2.6.4"
+version = "2.7.0"
 edition.workspace = true
 rust-version.workspace = true
 license-file = "../../LICENSE"
 build = "build.rs"
 
 [dependencies]
-anyhow = "1.0"
-easytier = { path = "../../easytier", version = "2.6.4", default-features = false, features = [
+anyhow.workspace = true
+easytier = { workspace = true, features = [
     "aes-gcm",
     "dhcp-ipv4",
     "logging",
@@ -18,4 +18,4 @@ easytier = { path = "../../easytier", version = "2.6.4", default-features = fals
     "tun",
     "web-client",
 ] }
-tokio = { version = "1", default-features = false, features = ["macros", "rt", "signal"] }
+tokio = { workspace = true, features = ["macros", "rt", "signal"] }

easytier-contrib/easytier-ohrs/Cargo.toml

@@ -1,3 +1,10 @@
+[workspace]
+members = [
+    "crates/easytier-ohos-features",
+    "crates/easytier-ohos-core",
+]
+resolver = "2"
+
 [package]
 name = "easytier-ohrs"
 version = "0.1.0"
@@ -9,17 +16,16 @@ crate-type=["cdylib"]
 [dependencies]
 anyhow = "1.0"
 async-trait = "0.1"
-base64 = "0.22"
 bytes = "1.5"
 easytier-core = { path = "../../easytier-core", default-features = false }
+easytier-ohos-features = { path = "crates/easytier-ohos-features" }
+easytier-ohos-core = { path = "crates/easytier-ohos-core" }
 easytier-proto = { path = "../../easytier-proto", default-features = false, features = [
     "api",
     "core",
     "json-rpc",
 ] }
-flate2 = "1.1"
 futures = "0.3"
-gethostname = "1.1"
 easytier = { path = "../../easytier" }
 napi-derive-ohos = "1.1"
 napi-ohos = { version = "1.1", default-features = false, features = [
@@ -34,15 +40,11 @@ napi-ohos = { version = "1.1", default-features = false, features = [
     "tokio_io_util",
     "deferred_trace",
     "napi8",
-    "node_version_detect",
     "web_stream",
 ] }
 once_cell = "1.21.3"
-ipnet = "2.10"
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0.125"
-prost-reflect = { version = "0.14.5", default-features = false, features = ["derive"] }
-rusqlite = { version = "0.32", features = ["bundled"] }
 tracing-subscriber = "0.3.19"
 tracing-core = "0.1.33"
 tracing = "0.1.41"

easytier-contrib/easytier-ohrs/crates/README.md

@@ -0,0 +1,29 @@
+# HarmonyOS Rust package boundaries
+
+`easytier-ohrs` keeps the single `.so`/HAR and N-API compatibility surface consumed by ArkTS, but its Rust implementation is split by responsibility:
+
+- **`easytier-ohos-core`** owns the process Tokio runtime, `NativeInstanceManager`, runtime-state projections, kernel socket protocol DTOs, TUN route aggregation, and the platform handshake used to protect individual transport sockets. Code that starts, stops, observes, or translates EasyTier runtime state belongs here.
+- **`easytier-ohos-features`** owns configuration persistence and migration, SQLite metadata/field storage, schema reflection, validation, import/export, and share links. Code that remains meaningful without a running EasyTier instance belongs here.
+- **`easytier-ohrs`** is the platform facade. It owns N-API exports, HarmonyOS platform logging and nearby-management adapters, and the small amount of orchestration that passes a validated feature configuration into the kernel package.
+
+## Dependency direction
+
+```text
+ArkTS/HAR
+   |
+easytier-ohrs (N-API facade)
+   |                    |
+   v                    v
+easytier-ohos-core     easytier-ohos-features
+```
+
+The facade passes owned EasyTier configuration values into the kernel package when runtime state must be projected. The kernel and feature packages do not depend on each other, so another HarmonyOS application can reuse the kernel integration without pulling in this client's SQLite repository, migrations, schema UI metadata, or share-link services.
+
+## Boundary rules
+
+1. SQLite, schema reflection, import/export, and share-link code must not enter `easytier-ohos-core`.
+2. Tokio runtime ownership, instance lifecycle, TUN attachment, kernel protocol, and runtime-state conversion must not enter `easytier-ohos-features`.
+3. New ArkTS exports remain in the outer `easytier-ohrs` facade so the HAR continues to expose one stable native module.
+4. Cross-package values should be owned DTOs/snapshots; feature code must not receive runtime-manager handles.
+5. Kernel code must not read the feature package's repository or global storage state; the facade supplies the validated runtime values it needs.
+6. The split is semantic and architectural. It is not presented as a configuration-page frame-time optimization.

easytier-contrib/easytier-ohrs/crates/easytier-ohos-core/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "easytier-ohos-core"
+version = "0.1.0"
+edition = "2024"
+description = "HarmonyOS-side EasyTier runtime, instance lifecycle and kernel interaction state"
+publish = false
+
+[dependencies]
+async-trait = "0.1"
+easytier = { path = "../../../../easytier" }
+easytier-core = { path = "../../../../easytier-core", default-features = false }
+ipnet = "2.10"
+once_cell = "1.21.3"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0.125"
+tokio = { version = "1", features = ["rt", "rt-multi-thread", "sync", "time"] }
+url = "2.5"

easytier-contrib/easytier-ohrs/crates/easytier-ohos-core/src/lib.rs

@@ -0,0 +1,56 @@
+pub mod protocol;
+pub mod routing;
+pub mod runtime;
+pub mod socket_protection;
+
+use easytier::instance::factory::{NativeInstanceManager, native_instance_manager_with_runtime};
+use once_cell::sync::Lazy;
+use std::sync::Arc;
+use tokio::runtime::{Builder, Runtime};
+
+/// The single Tokio runtime that owns HarmonyOS kernel and web-client work.
+pub static ASYNC_RUNTIME: Lazy<Runtime> = Lazy::new(|| {
+    Builder::new_multi_thread()
+        .enable_all()
+        .build()
+        .expect("tokio runtime for easytier-ohos-core")
+});
+
+/// Process-wide EasyTier instance manager. Keeping it in the kernel crate prevents feature/storage
+/// code from acquiring lifecycle ownership.
+pub static INSTANCE_MANAGER: Lazy<Arc<NativeInstanceManager>> = Lazy::new(|| {
+    Arc::new(native_instance_manager_with_runtime(
+        ASYNC_RUNTIME.handle().clone(),
+    ))
+});
+
+#[cfg(test)]
+mod architecture_tests {
+    fn assert_no_napi_annotations(path: &std::path::Path) {
+        for entry in std::fs::read_dir(path).expect("read source directory") {
+            let path = entry.expect("read source entry").path();
+            if path.is_dir() {
+                assert_no_napi_annotations(&path);
+            } else if path.extension().is_some_and(|extension| extension == "rs") {
+                let source = std::fs::read_to_string(&path).expect("read Rust source");
+                let marker = ["#[", "napi"].concat();
+                assert!(!source.contains(&marker), "N-API annotation in {path:?}");
+            }
+        }
+    }
+
+    #[test]
+    fn inner_crate_has_no_napi_registration_dependency() {
+        let manifest = include_str!("../Cargo.toml");
+        let runtime_dependency = ["napi", "ohos"].join("-");
+        let derive_dependency = ["napi", "derive", "ohos"].join("-");
+        assert!(!manifest.contains(&runtime_dependency));
+        assert!(!manifest.contains(&derive_dependency));
+        assert!(!manifest.contains("easytier-ohos-features"));
+        assert_no_napi_annotations(
+            std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
+                .join("src")
+                .as_path(),
+        );
+    }
+}

easytier-contrib/easytier-ohrs/crates/easytier-ohos-core/src/protocol.rs

@@ -1,11 +1,17 @@
-use crate::config::types::stored_config::LocalSocketSyncMessage;
 use serde::Serialize;
 use std::io::{Error, ErrorKind, Write};
 use std::os::unix::net::UnixStream;
 
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
-pub(crate) struct TunRequestPayload {
+pub struct LocalSocketSyncMessage {
+    pub message_type: String,
+    pub payload_json: String,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct TunRequestPayload {
     pub config_id: String,
     pub instance_id: String,
     pub display_name: String,
@@ -16,7 +22,7 @@ pub(crate) struct TunRequestPayload {
     pub need_exit_node: bool,
 }
 
-pub(crate) fn send_local_socket_message(
+pub fn send_local_socket_message(
     stream: &mut UnixStream,
     message_type: &str,
     payload_json: String,
@@ -39,7 +45,7 @@ fn shrink_clients_if_sparse(clients: &mut Vec<UnixStream>) {
     }
 }
 
-pub(crate) fn broadcast_local_socket_message(
+pub fn broadcast_local_socket_message(
     clients: &mut Vec<UnixStream>,
     message_type: &str,
     payload_json: &str,
@@ -57,7 +63,7 @@ pub(crate) fn broadcast_local_socket_message(
     delivered
 }
 
-pub(crate) fn send_local_socket_json_payload_message(
+pub fn send_local_socket_json_payload_message(
     stream: &mut UnixStream,
     message_type: &str,
     payload_json: &str,
@@ -74,7 +80,7 @@ pub(crate) fn send_local_socket_json_payload_message(
     Ok(())
 }
 
-pub(crate) fn broadcast_local_socket_json_payload_message(
+pub fn broadcast_local_socket_json_payload_message(
     clients: &mut Vec<UnixStream>,
     message_type: &str,
     payload_json: &str,
@@ -91,3 +97,41 @@ pub(crate) fn broadcast_local_socket_json_payload_message(
     *clients = active_clients;
     delivered
 }
+
+#[cfg(test)]
+mod tests {
+    use super::{broadcast_local_socket_message, send_local_socket_message};
+    use std::io::Read;
+    use std::os::unix::net::UnixStream;
+
+    #[test]
+    fn local_socket_message_uses_camel_case_newline_frame() {
+        let (mut sender, mut receiver) = UnixStream::pair().expect("socket pair");
+        send_local_socket_message(&mut sender, "runtimeState", "{\"ok\":true}".to_string())
+            .expect("send frame");
+        sender
+            .shutdown(std::net::Shutdown::Write)
+            .expect("shutdown");
+
+        let mut raw = String::new();
+        receiver.read_to_string(&mut raw).expect("read frame");
+        assert_eq!(
+            raw,
+            "{\"messageType\":\"runtimeState\",\"payloadJson\":\"{\\\"ok\\\":true}\"}\n"
+        );
+    }
+
+    #[test]
+    fn broadcast_removes_disconnected_clients() {
+        let (sender, receiver) = UnixStream::pair().expect("socket pair");
+        drop(receiver);
+        let mut clients = vec![sender];
+
+        assert!(!broadcast_local_socket_message(
+            &mut clients,
+            "runtimeState",
+            "{}"
+        ));
+        assert!(clients.is_empty());
+    }
+}

easytier-contrib/easytier-ohrs/crates/easytier-ohos-core/src/routing.rs

@@ -1,4 +1,3 @@
-use crate::config::repository::get_runtime_config_manual_routes;
 use crate::runtime::state::runtime_state::RuntimeInstanceState;
 use ipnet::IpNet;
 use std::collections::HashSet;
@@ -54,12 +53,11 @@ fn simplify_routes(routes: Vec<String>) -> Vec<String> {
         .collect()
 }
 
-pub(crate) fn aggregate_tun_routes(instance: &RuntimeInstanceState) -> Vec<String> {
+pub fn aggregate_tun_routes(instance: &RuntimeInstanceState) -> Vec<String> {
     let virtual_ipv4_cidr = instance
         .my_node_info
         .as_ref()
         .and_then(|info| info.virtual_ipv4_cidr.clone());
-    let manual_routes = get_runtime_config_manual_routes(&instance.config_id);
     let runtime_proxy_cidrs = instance
         .routes
         .iter()
@@ -71,15 +69,15 @@ pub(crate) fn aggregate_tun_routes(instance: &RuntimeInstanceState) -> Vec<Strin
         raw_routes.push(cidr);
     }
 
-    raw_routes.extend(manual_routes.iter().cloned());
-    // Locally configured proxy CIDRs are advertisements for networks reached
-    // through this node. Installing them into this node's TUN would recapture
-    // the proxy's own destination sockets instead of using the physical LAN.
+    raw_routes.extend(instance.manual_routes.iter().cloned());
+    // Local proxy CIDRs are advertisements for networks reached through this
+    // node. Installing them into the same local TUN would recapture the proxy's
+    // own destination sockets instead of using the physical network.
     raw_routes.extend(runtime_proxy_cidrs.iter().cloned());
     simplify_routes(raw_routes)
 }
 
-pub(crate) fn aggregate_requested_tun_routes(instances: &[RuntimeInstanceState]) -> Vec<String> {
+pub fn aggregate_requested_tun_routes(instances: &[RuntimeInstanceState]) -> Vec<String> {
     let mut aggregated_routes = Vec::new();
     let mut seen_routes = HashSet::new();
     for instance in instances.iter().filter(|instance| instance.tun_required) {
@@ -94,69 +92,55 @@ pub(crate) fn aggregate_requested_tun_routes(instances: &[RuntimeInstanceState])
 
 #[cfg(test)]
 mod tests {
-    use super::*;
-    use crate::config::repository::{cache_runtime_config_snapshot, clear_runtime_config_snapshot};
-    use crate::runtime::state::runtime_state::{MyNodeInfo, RouteView};
+    use super::{aggregate_tun_routes, simplify_routes};
+    use crate::runtime::state::runtime_state::{RouteView, runtime_instance_from_config_snapshot};
     use easytier::proto::api::manage::NetworkConfig;
 
-    fn runtime_instance(config_id: &str) -> RuntimeInstanceState {
-        RuntimeInstanceState {
-            config_id: config_id.to_string(),
-            instance_id: "test-instance".to_string(),
-            display_name: "test".to_string(),
-            running: true,
-            tun_required: true,
-            tun_attached: false,
-            magic_dns_enabled: false,
-            need_exit_node: false,
-            error_message: None,
-            my_node_info: Some(MyNodeInfo {
-                virtual_ipv4: Some("10.144.144.1".to_string()),
-                virtual_ipv4_cidr: Some("10.144.144.1/24".to_string()),
-                hostname: None,
-                version: None,
-                peer_id: Some(1),
-                listeners: Vec::new(),
-                vpn_portal_cfg: None,
-                udp_nat_type: None,
-                tcp_nat_type: None,
-            }),
-            events: Vec::new(),
-            routes: vec![RouteView {
-                peer_id: 2,
-                hostname: None,
-                ipv4: Some("10.144.144.2".to_string()),
-                ipv4_cidr: Some("10.144.144.2/24".to_string()),
-                ipv6_cidr: None,
-                proxy_cidrs: vec!["10.20.0.0/16".to_string()],
-                next_hop_peer_id: Some(2),
-                cost: Some(1),
-                path_latency: None,
-                udp_nat_type: None,
-                tcp_nat_type: None,
-                inst_id: None,
-                version: None,
-                is_public_server: None,
-            }],
-            peers: Vec::new(),
-        }
+    #[test]
+    fn simplify_routes_normalizes_deduplicates_and_removes_subnets() {
+        let routes = simplify_routes(vec![
+            "10.0.0.7".to_string(),
+            "10.0.0.0/24".to_string(),
+            "10.0.0.42/32->peer-a".to_string(),
+            "2001:db8::1".to_string(),
+            "2001:db8::/64".to_string(),
+        ]);
+
+        assert_eq!(routes, vec!["10.0.0.0/24", "2001:db8::/64"]);
     }
 
     #[test]
     fn local_proxy_cidr_is_not_installed_in_tun_routes() {
-        let config_id = "routing-test-local-proxy";
-        cache_runtime_config_snapshot(
-            config_id.to_string(),
+        let mut instance = runtime_instance_from_config_snapshot(
+            "routing-test".to_string(),
             "test".to_string(),
             NetworkConfig {
+                virtual_ipv4: Some("10.144.144.1".to_string()),
+                network_length: Some(24),
                 routes: vec!["172.16.0.0/16".to_string()],
                 proxy_cidrs: vec!["192.168.1.0/24".to_string()],
                 ..Default::default()
             },
+            true,
         );
+        instance.routes.push(RouteView {
+            peer_id: 2,
+            hostname: None,
+            ipv4: Some("10.144.144.2".to_string()),
+            ipv4_cidr: Some("10.144.144.2/24".to_string()),
+            ipv6_cidr: None,
+            proxy_cidrs: vec!["10.20.0.0/16".to_string()],
+            next_hop_peer_id: Some(2),
+            cost: Some(1),
+            path_latency: None,
+            udp_nat_type: None,
+            tcp_nat_type: None,
+            inst_id: None,
+            version: None,
+            is_public_server: None,
+        });
 
-        let routes = aggregate_tun_routes(&runtime_instance(config_id));
-        clear_runtime_config_snapshot(config_id);
+        let routes = aggregate_tun_routes(&instance);
 
         assert!(routes.contains(&"10.144.144.0/24".to_string()));
         assert!(routes.contains(&"172.16.0.0/16".to_string()));

easytier-contrib/easytier-ohrs/crates/easytier-ohos-core/src/runtime.rs

@@ -0,0 +1 @@
+pub mod state;

easytier-contrib/easytier-ohrs/crates/easytier-ohos-core/src/runtime/state/mod.rs

@@ -0,0 +1 @@
+pub mod runtime_state;

easytier-contrib/easytier-ohrs/crates/easytier-ohos-core/src/runtime/state/runtime_state.rs

@@ -1,5 +1,4 @@
 use easytier::proto::{api, common};
-use napi_derive_ohos::napi;
 use serde::Serialize;
 use std::collections::HashSet;
 use std::sync::Mutex;
@@ -29,7 +28,6 @@ pub fn is_tun_attached(instance_id: &str) -> bool {
 
 #[derive(Serialize)]
 #[serde(rename_all = "camelCase")]
-#[napi(object)]
 pub struct PeerConnStats {
     pub rx_bytes: i64,
     pub tx_bytes: i64,
@@ -40,7 +38,6 @@ pub struct PeerConnStats {
 
 #[derive(Serialize)]
 #[serde(rename_all = "camelCase")]
-#[napi(object)]
 pub struct PeerConnInfo {
     pub conn_id: String,
     pub my_peer_id: i64,
@@ -61,7 +58,6 @@ pub struct PeerConnInfo {
 
 #[derive(Serialize)]
 #[serde(rename_all = "camelCase")]
-#[napi(object)]
 pub struct PeerInfo {
     pub peer_id: i64,
     pub default_conn_id: Option<String>,
@@ -71,7 +67,6 @@ pub struct PeerInfo {
 
 #[derive(Serialize)]
 #[serde(rename_all = "camelCase")]
-#[napi(object)]
 pub struct RouteView {
     pub peer_id: i64,
     pub hostname: Option<String>,
@@ -91,7 +86,6 @@ pub struct RouteView {
 
 #[derive(Serialize)]
 #[serde(rename_all = "camelCase")]
-#[napi(object)]
 pub struct MyNodeInfo {
     pub virtual_ipv4: Option<String>,
     pub virtual_ipv4_cidr: Option<String>,
@@ -106,7 +100,6 @@ pub struct MyNodeInfo {
 
 #[derive(Serialize)]
 #[serde(rename_all = "camelCase")]
-#[napi(object)]
 pub struct RuntimeInstanceState {
     pub config_id: String,
     pub instance_id: String,
@@ -121,11 +114,12 @@ pub struct RuntimeInstanceState {
     pub events: Vec<String>,
     pub routes: Vec<RouteView>,
     pub peers: Vec<PeerInfo>,
+    #[serde(skip)]
+    pub manual_routes: Vec<String>,
 }
 
 #[derive(Serialize)]
 #[serde(rename_all = "camelCase")]
-#[napi(object)]
 pub struct TunAggregateState {
     pub active: bool,
     pub attached_instance_ids: Vec<String>,
@@ -136,7 +130,6 @@ pub struct TunAggregateState {
 
 #[derive(Serialize)]
 #[serde(rename_all = "camelCase")]
-#[napi(object)]
 pub struct RuntimeAggregateState {
     pub instances: Vec<RuntimeInstanceState>,
     pub tun: TunAggregateState,
@@ -324,7 +317,7 @@ fn route_to_view(route: api::instance::Route) -> RouteView {
     }
 }
 
-pub(crate) fn peer_conn_to_view(conn: api::instance::PeerConnInfo) -> PeerConnInfo {
+pub fn peer_conn_to_view(conn: api::instance::PeerConnInfo) -> PeerConnInfo {
     let stats = conn.stats.map(|stats| PeerConnStats {
         rx_bytes: stats.rx_bytes as i64,
         tx_bytes: stats.tx_bytes as i64,
@@ -399,12 +392,22 @@ fn my_node_info_to_view(info: api::manage::MyNodeInfo) -> MyNodeInfo {
 pub fn runtime_instance_from_running_info(
     config_id: String,
     display_name: String,
-    magic_dns_enabled: bool,
-    need_exit_node: bool,
+    config: Option<api::manage::NetworkConfig>,
     info: api::manage::NetworkInstanceRunningInfo,
 ) -> RuntimeInstanceState {
     let tun_attached = info.running && is_tun_attached(&config_id);
     let tun_required = info.running && (info.dev_name != "no_tun" || tun_attached);
+    let magic_dns_enabled = config
+        .as_ref()
+        .and_then(|config| config.enable_magic_dns)
+        .unwrap_or(false);
+    let need_exit_node = config
+        .as_ref()
+        .is_some_and(|config| !config.exit_nodes.is_empty());
+    let manual_routes = config
+        .as_ref()
+        .map(|config| config.routes.clone())
+        .unwrap_or_default();
 
     RuntimeInstanceState {
         config_id: config_id.clone(),
@@ -420,6 +423,7 @@ pub fn runtime_instance_from_running_info(
         events: info.events,
         routes: info.routes.into_iter().map(route_to_view).collect(),
         peers: info.peers.into_iter().map(peer_to_view).collect(),
+        manual_routes,
     }
 }
 
@@ -434,6 +438,7 @@ pub fn runtime_instance_from_config_snapshot(
         running && (config.dev_name.as_deref().unwrap_or("") != "no_tun" || tun_attached);
     let endpoint_urls = config_endpoint_urls(&config);
     let public_server_url = non_empty_string(config.public_server_url.clone());
+    let manual_routes = config.routes.clone();
     let my_node_info = MyNodeInfo {
         virtual_ipv4: non_empty_string(config.virtual_ipv4.clone()),
         virtual_ipv4_cidr: config_virtual_ipv4_cidr(&config),
@@ -460,5 +465,6 @@ pub fn runtime_instance_from_config_snapshot(
         events: Vec::new(),
         routes: configured_route_views(&endpoint_urls, public_server_url.as_deref()),
         peers: configured_peer_views(&endpoint_urls),
+        manual_routes,
     }
 }

easytier-contrib/easytier-ohrs/crates/easytier-ohos-core/src/socket_protection.rs

@@ -0,0 +1,255 @@
+use std::{
+    collections::{HashMap, VecDeque},
+    io,
+    os::fd::{AsRawFd, BorrowedFd, OwnedFd},
+    sync::{Arc, Mutex},
+};
+
+use async_trait::async_trait;
+use easytier::socket_protector::{NativeSocketProtector, set_native_socket_protector};
+use once_cell::sync::Lazy;
+use tokio::sync::{Notify, oneshot};
+
+const MAX_PENDING_SOCKET_PROTECTIONS: usize = 128;
+
+#[derive(Debug, Clone)]
+pub struct SocketProtectionRequest {
+    pub request_id: u64,
+    pub socket_fd: i32,
+    pub purpose: String,
+}
+
+#[derive(Default)]
+struct SocketProtectionState {
+    enabled: bool,
+    next_request_id: u64,
+    queued: VecDeque<SocketProtectionRequest>,
+    pending: HashMap<u64, PendingSocketProtection>,
+}
+
+struct PendingSocketProtection {
+    completion: oneshot::Sender<io::Result<()>>,
+    _socket: OwnedFd,
+}
+
+#[derive(Default)]
+pub struct SocketProtectionManager {
+    state: Mutex<SocketProtectionState>,
+    request_ready: Notify,
+}
+
+pub static SOCKET_PROTECTION_MANAGER: Lazy<Arc<SocketProtectionManager>> =
+    Lazy::new(|| Arc::new(SocketProtectionManager::default()));
+
+impl SocketProtectionManager {
+    fn enable(&self) {
+        let mut state = self
+            .state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        state.enabled = true;
+    }
+
+    fn disable(&self) {
+        let queued = {
+            let mut state = self
+                .state
+                .lock()
+                .unwrap_or_else(std::sync::PoisonError::into_inner);
+            state.enabled = false;
+            let queued_ids = state
+                .queued
+                .drain(..)
+                .map(|request| request.request_id)
+                .collect::<Vec<_>>();
+            queued_ids
+                .into_iter()
+                .filter_map(|request_id| state.pending.remove(&request_id))
+                .map(|pending| pending.completion)
+                .collect::<Vec<_>>()
+        };
+        self.request_ready.notify_waiters();
+        for sender in queued {
+            let _ = sender.send(Err(io::Error::new(
+                io::ErrorKind::Interrupted,
+                "native socket protection stopped",
+            )));
+        }
+    }
+
+    pub async fn next_request(&self) -> Option<SocketProtectionRequest> {
+        loop {
+            let notified = self.request_ready.notified();
+            {
+                let mut state = self
+                    .state
+                    .lock()
+                    .unwrap_or_else(std::sync::PoisonError::into_inner);
+                if let Some(request) = state.queued.pop_front() {
+                    return Some(request);
+                }
+                if !state.enabled {
+                    return None;
+                }
+            }
+            notified.await;
+        }
+    }
+
+    pub fn complete_request(&self, request_id: u64, success: bool, error: Option<String>) -> bool {
+        let pending = self
+            .state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .pending
+            .remove(&request_id);
+        let Some(pending) = pending else {
+            return false;
+        };
+        let result = if success {
+            Ok(())
+        } else {
+            Err(io::Error::other(error.unwrap_or_else(|| {
+                "native socket protection failed".to_string()
+            })))
+        };
+        pending.completion.send(result).is_ok()
+    }
+}
+
+#[async_trait]
+impl NativeSocketProtector for SocketProtectionManager {
+    async fn protect(&self, socket_handle: u64) -> io::Result<()> {
+        let socket_fd = i32::try_from(socket_handle).map_err(|_| {
+            io::Error::new(
+                io::ErrorKind::InvalidInput,
+                format!("socket handle {socket_handle} does not fit a HarmonyOS fd"),
+            )
+        })?;
+        // Keep a duplicate alive across the ArkTS Promise. Socket options set
+        // through it affect the same socket, while cancellation cannot turn the
+        // request into a stale, reused descriptor.
+        let protected_socket = unsafe { BorrowedFd::borrow_raw(socket_fd) }.try_clone_to_owned()?;
+        let protected_fd = protected_socket.as_raw_fd();
+        let (sender, receiver) = oneshot::channel();
+        let request_id = {
+            let mut state = self
+                .state
+                .lock()
+                .unwrap_or_else(std::sync::PoisonError::into_inner);
+            if !state.enabled {
+                return Err(io::Error::new(
+                    io::ErrorKind::NotConnected,
+                    "native socket protection is not active",
+                ));
+            }
+            if state.pending.len() >= MAX_PENDING_SOCKET_PROTECTIONS {
+                return Err(io::Error::new(
+                    io::ErrorKind::WouldBlock,
+                    "too many pending native socket protection requests",
+                ));
+            }
+            state.next_request_id = state.next_request_id.wrapping_add(1).max(1);
+            let request_id = state.next_request_id;
+            state.queued.push_back(SocketProtectionRequest {
+                request_id,
+                socket_fd: protected_fd,
+                // Keep the existing ArkTS request shape without native policy labels.
+                purpose: "socket".to_owned(),
+            });
+            state.pending.insert(
+                request_id,
+                PendingSocketProtection {
+                    completion: sender,
+                    _socket: protected_socket,
+                },
+            );
+            request_id
+        };
+        self.request_ready.notify_one();
+        receiver.await.map_err(|_| {
+            io::Error::new(
+                io::ErrorKind::Interrupted,
+                format!("socket protection request {request_id} was cancelled"),
+            )
+        })?
+    }
+}
+
+pub fn enable_socket_protection() -> bool {
+    SOCKET_PROTECTION_MANAGER.enable();
+    set_native_socket_protector(Some(SOCKET_PROTECTION_MANAGER.clone()));
+    true
+}
+
+pub fn disable_socket_protection() -> bool {
+    set_native_socket_protector(None);
+    SOCKET_PROTECTION_MANAGER.disable();
+    true
+}
+
+pub fn fail_socket_protection() -> bool {
+    // Keep the disabled manager installed so an unexpected ArkTS pump failure
+    // remains fail-closed for every subsequently created transport socket.
+    SOCKET_PROTECTION_MANAGER.disable();
+    true
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use easytier::socket_protector::NativeSocketProtector;
+    use std::os::fd::AsRawFd;
+
+    #[test]
+    fn transport_socket_waits_for_platform_completion() {
+        let runtime = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .unwrap();
+        runtime.block_on(async {
+            let manager = Arc::new(SocketProtectionManager::default());
+            manager.enable();
+            let socket = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
+            let socket_fd = socket.as_raw_fd();
+            let task = tokio::spawn({
+                let manager = manager.clone();
+                async move { manager.protect(socket_fd as u64).await }
+            });
+            let request = manager.next_request().await.unwrap();
+            assert_ne!(request.socket_fd, socket_fd);
+            assert!(manager.complete_request(request.request_id, true, None));
+            task.await.unwrap().unwrap();
+        });
+    }
+
+    #[test]
+    fn dispatched_socket_is_retained_during_shutdown() {
+        let runtime = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .unwrap();
+        runtime.block_on(async {
+            let manager = Arc::new(SocketProtectionManager::default());
+            manager.enable();
+            let socket = std::net::UdpSocket::bind("127.0.0.1:0").unwrap();
+            let socket_fd = socket.as_raw_fd();
+            let task = tokio::spawn({
+                let manager = manager.clone();
+                async move { manager.protect(socket_fd as u64).await }
+            });
+            let request = manager.next_request().await.unwrap();
+
+            manager.disable();
+            tokio::task::yield_now().await;
+            assert!(!task.is_finished());
+
+            assert!(manager.complete_request(
+                request.request_id,
+                false,
+                Some("shutdown".to_string()),
+            ));
+            assert!(task.await.unwrap().is_err());
+        });
+    }
+}

easytier-contrib/easytier-ohrs/crates/easytier-ohos-features/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "easytier-ohos-features"
+version = "0.1.0"
+edition = "2024"
+description = "HarmonyOS-side EasyTier configuration, schema, persistence and sharing features"
+publish = false
+
+[dependencies]
+base64 = "0.22"
+easytier = { path = "../../../../easytier" }
+flate2 = "1.1"
+gethostname = "1.1"
+once_cell = "1.21.3"
+prost-reflect = { version = "0.14.5", default-features = false, features = ["derive"] }
+rusqlite = { version = "0.32", features = ["bundled"] }
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0.125"
+tracing = "0.1.41"
+url = "2.5"
+uuid = { version = "1.5.0", features = ["v4", "fast-rng", "macro-diagnostics", "serde"] }

easytier-contrib/easytier-ohrs/crates/easytier-ohos-features/src/config.rs

@@ -0,0 +1,4 @@
+pub mod repository;
+pub mod services;
+pub mod storage;
+pub mod types;

easytier-contrib/easytier-ohrs/crates/easytier-ohos-features/src/config/services/mod.rs

@@ -0,0 +1,2 @@
+pub mod schema_service;
+pub mod share_link_service;

easytier-contrib/easytier-ohrs/crates/easytier-ohos-features/src/config/services/schema_service.rs

@@ -1,18 +1,15 @@
 use easytier::proto::ALL_DESCRIPTOR_BYTES;
-use napi_derive_ohos::napi;
 use once_cell::sync::Lazy;
 use prost_reflect::{Cardinality, DescriptorPool, FieldDescriptor, Kind, MessageDescriptor};
 use serde::Serialize;
 
 #[derive(Debug, Clone, Serialize)]
-#[napi(object)]
 pub struct FieldOption {
     pub label: String,
     pub value: String,
 }
 
 #[derive(Debug, Clone, Serialize)]
-#[napi(object)]
 pub struct ValidationRule {
     pub rule_type: String,
     pub arg: String,
@@ -20,7 +17,6 @@ pub struct ValidationRule {
 }
 
 #[derive(Debug, Clone, Serialize)]
-#[napi(object)]
 pub struct NetworkConfigSchema {
     pub node_kind: String,
     pub name: String,
@@ -38,7 +34,6 @@ pub struct NetworkConfigSchema {
 }
 
 #[derive(Debug, Clone, Serialize)]
-#[napi(object)]
 pub struct ConfigFieldMapping {
     pub field_name: String,
     pub field_number: i32,
@@ -119,10 +114,9 @@ fn enum_options(kind: Kind) -> Vec<FieldOption> {
             .values()
             .map(|value| FieldOption {
                 label: value.name().to_string(),
-                // protobuf JSON uses enum names rather than their numeric wire values.
-                // Returning the number here made ArkTS write (for example) `1`, while
-                // NetworkConfig deserialization expects `"None"`, so field-level saves
-                // were rejected by the repository validation step.
+                // Protobuf JSON uses enum names rather than numeric wire values.
+                // Returning the number made ArkTS write `1`, while NetworkConfig
+                // deserialization expects a name such as `"None"`.
                 value: value.name().to_string(),
             })
             .collect(),

easytier-contrib/easytier-ohrs/crates/easytier-ohos-features/src/config/services/share_link_service.rs

@@ -178,20 +178,21 @@ mod tests {
 
     #[test]
     fn share_link_roundtrip_works() {
+        const CONFIG_ID: &str = "00000000-0000-0000-0000-000000000003";
         assert!(init_config_store(test_root()));
-        create_config_record("cfg-share".to_string(), "share-demo".to_string())
+        create_config_record(CONFIG_ID.to_string(), "share-demo".to_string())
             .expect("create config");
 
-        let link = build_config_share_link("cfg-share", None, true).expect("share link");
+        let link = build_config_share_link(CONFIG_ID, None, true).expect("share link");
         let payload = parse_config_share_link(&link).expect("parse link");
         let config =
             serde_json::from_str::<NetworkConfig>(&payload.config_json).expect("config json");
 
         assert!(payload.only_start);
         assert_eq!(payload.display_name.as_deref(), Some("share-demo"));
-        assert_ne!(config.instance_id.as_deref(), Some("cfg-share"));
+        assert_ne!(config.instance_id.as_deref(), Some(CONFIG_ID));
 
         let imported_id = import_config_share_link(&link, None).expect("import link");
-        assert_ne!(imported_id, "cfg-share");
+        assert_ne!(imported_id, CONFIG_ID);
     }
 }

easytier-contrib/easytier-ohrs/crates/easytier-ohos-features/src/config/storage/mod.rs

@@ -0,0 +1 @@
+pub mod config_meta;

easytier-contrib/easytier-ohrs/crates/easytier-ohos-features/src/config/types/mod.rs

@@ -0,0 +1 @@
+pub mod stored_config;

easytier-contrib/easytier-ohrs/crates/easytier-ohos-features/src/config/types/stored_config.rs

@@ -1,9 +1,7 @@
-use napi_derive_ohos::napi;
 use serde::Serialize;
 
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
-#[napi(object)]
 pub struct StoredConfigMeta {
     pub config_id: String,
     pub display_name: String,
@@ -15,7 +13,6 @@ pub struct StoredConfigMeta {
 
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
-#[napi(object)]
 pub struct StoredConfigRecord {
     pub meta: StoredConfigMeta,
     pub config_json: String,
@@ -23,21 +20,18 @@ pub struct StoredConfigRecord {
 
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
-#[napi(object)]
 pub struct StoredConfigList {
     pub configs: Vec<StoredConfigMeta>,
 }
 
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
-#[napi(object)]
 pub struct ExportTomlResult {
     pub toml_text: String,
 }
 
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
-#[napi(object)]
 pub struct SharedConfigLinkPayload {
     pub config_json: String,
     pub display_name: Option<String>,
@@ -45,15 +39,6 @@ pub struct SharedConfigLinkPayload {
 }
 
 #[derive(Debug, Clone, Serialize)]
-#[serde(rename_all = "camelCase")]
-#[napi(object)]
-pub struct LocalSocketSyncMessage {
-    pub message_type: String,
-    pub payload_json: String,
-}
-
-#[derive(Debug, Clone, Serialize)]
-#[napi(object)]
 pub struct KeyValuePair {
     pub key: String,
     pub value: String,
@@ -61,7 +46,6 @@ pub struct KeyValuePair {
 
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
-#[napi(object)]
 pub struct SnapshotImportResult {
     pub ok: bool,
     pub error_code: String,

easytier-contrib/easytier-ohrs/crates/easytier-ohos-features/src/config_repo.rs

@@ -4,7 +4,9 @@ use crate::config::storage::config_meta::{
     reset_config_meta_store, upsert_config_meta_in_tx,
 };
 use crate::config::types::stored_config::{ExportTomlResult, StoredConfigRecord};
+use easytier::common::config::{NetworkConfigExt, TomlConfigLoader};
 use easytier::proto::api::manage::NetworkConfig;
+use easytier::proto::common::CompressionAlgoPb;
 use once_cell::sync::Lazy;
 use rusqlite::params;
 use serde_json::Value;
@@ -16,16 +18,16 @@ use std::time::Instant;
 static CONFIG_ROOT_DIR: Mutex<Option<PathBuf>> = Mutex::new(None);
 static RUNTIME_CONFIG_SNAPSHOTS: Lazy<Mutex<HashMap<String, RuntimeConfigSnapshot>>> =
     Lazy::new(|| Mutex::new(HashMap::new()));
-pub(crate) const CONFIG_DIR_NAME: &str = "easytier-configs";
-pub(crate) const KERNEL_SOCKET_FILE_NAME: &str = "easytier-kernel.sock";
+pub const CONFIG_DIR_NAME: &str = "easytier-configs";
+pub const KERNEL_SOCKET_FILE_NAME: &str = "easytier-kernel.sock";
 
 #[derive(Clone)]
-pub(crate) struct RuntimeConfigSnapshot {
+pub struct RuntimeConfigSnapshot {
     pub display_name: String,
     pub config: NetworkConfig,
 }
 
-pub(crate) fn cache_runtime_config_snapshot(
+pub fn cache_runtime_config_snapshot(
     config_id: String,
     display_name: String,
     config: NetworkConfig,
@@ -41,39 +43,27 @@ pub(crate) fn cache_runtime_config_snapshot(
     }
 }
 
-pub(crate) fn clear_runtime_config_snapshot(config_id: &str) {
+pub fn clear_runtime_config_snapshot(config_id: &str) {
     if let Ok(mut guard) = RUNTIME_CONFIG_SNAPSHOTS.lock() {
         guard.remove(config_id);
     }
 }
 
-pub(crate) fn get_runtime_config_snapshot(config_id: &str) -> Option<RuntimeConfigSnapshot> {
+pub fn get_runtime_config_snapshot(config_id: &str) -> Option<RuntimeConfigSnapshot> {
     RUNTIME_CONFIG_SNAPSHOTS
         .lock()
         .ok()
         .and_then(|guard| guard.get(config_id).cloned())
 }
 
-pub(crate) fn get_runtime_config_manual_routes(config_id: &str) -> Vec<String> {
-    RUNTIME_CONFIG_SNAPSHOTS
-        .lock()
-        .ok()
-        .and_then(|guard| {
-            guard
-                .get(config_id)
-                .map(|snapshot| snapshot.config.routes.clone())
-        })
-        .unwrap_or_default()
-}
-
-pub(crate) fn config_root_dir() -> Option<PathBuf> {
+pub fn config_root_dir() -> Option<PathBuf> {
     CONFIG_ROOT_DIR
         .lock()
         .ok()
         .and_then(|guard| guard.as_ref().cloned())
 }
 
-pub(crate) fn kernel_socket_path() -> Option<PathBuf> {
+pub fn kernel_socket_path() -> Option<PathBuf> {
     config_root_dir().map(|root| root.join(KERNEL_SOCKET_FILE_NAME))
 }
 
@@ -277,7 +267,9 @@ pub fn set_config_field_value(config_id: &str, field: &str, json_value: &str) ->
 }
 
 pub fn get_default_config_json() -> Option<String> {
-    crate::build_default_network_config_json().ok()
+    let mut config = NetworkConfig::new_from_config(TomlConfigLoader::default()).ok()?;
+    config.data_compress_algo = Some(CompressionAlgoPb::None as i32);
+    serde_json::to_string(&config).ok()
 }
 
 pub fn create_config_record(config_id: String, display_name: String) -> Option<StoredConfigRecord> {
@@ -289,24 +281,6 @@ pub fn create_config_record(config_id: String, display_name: String) -> Option<S
     save_config_record(config_id, display_name, normalized_json)
 }
 
-pub fn start_kernel_with_config_id(config_id: &str) -> bool {
-    if validation::validate_config_id(config_id).is_err() {
-        return false;
-    }
-    let raw = match load_config_json(config_id) {
-        Some(raw) => raw,
-        None => return false,
-    };
-    let display_name = get_config_meta(config_id)
-        .map(|meta| meta.display_name)
-        .unwrap_or_else(|| config_id.to_string());
-    let started = crate::run_network_instance_from_json(&raw);
-    if started && let Ok(config) = serde_json::from_str::<NetworkConfig>(&raw) {
-        cache_runtime_config_snapshot(config_id.to_string(), display_name, config);
-    }
-    started
-}
-
 pub fn list_config_meta_json() -> String {
     serde_json::to_string(&list_config_meta_entries().configs).unwrap_or_else(|_| "[]".to_string())
 }
@@ -376,23 +350,28 @@ mod tests {
 
     #[test]
     fn save_get_export_delete_roundtrip() {
+        const CONFIG_ID: &str = "00000000-0000-0000-0000-000000000001";
         let root = test_root();
         assert!(init_config_store(root.clone()));
 
-        let config_json = crate::build_default_network_config_json().expect("default config");
-        let saved = save_config_record("cfg-1".to_string(), "test-config".to_string(), config_json)
-            .expect("save config");
+        let config_json = get_default_config_json().expect("default config");
+        let saved = save_config_record(
+            CONFIG_ID.to_string(),
+            "test-config".to_string(),
+            config_json,
+        )
+        .expect("save config");
 
-        assert_eq!(saved.meta.config_id, "cfg-1");
+        assert_eq!(saved.meta.config_id, CONFIG_ID);
         assert_eq!(saved.meta.display_name, "test-config");
 
-        let loaded = get_config_record("cfg-1").expect("load config");
+        let loaded = get_config_record(CONFIG_ID).expect("load config");
         assert_eq!(loaded.meta.display_name, "test-config");
-        assert!(loaded.config_json.contains("cfg-1"));
+        assert!(loaded.config_json.contains(CONFIG_ID));
 
         let legacy_json_path = PathBuf::from(&root)
             .join(CONFIG_DIR_NAME)
-            .join("cfg-1.json");
+            .join(format!("{CONFIG_ID}.json"));
         assert!(
             !legacy_json_path.exists(),
             "config should no longer be persisted as a per-config json file"
@@ -402,52 +381,54 @@ mod tests {
         let field_count: i64 = conn
             .query_row(
                 "SELECT COUNT(*) FROM stored_config_fields WHERE config_id = ?1",
-                params!["cfg-1"],
+                params![CONFIG_ID],
                 |row| row.get(0),
             )
             .expect("count config fields");
+        drop(conn);
         assert!(field_count > 0, "config fields should be stored in sqlite");
 
-        let exported = export_config_toml("cfg-1").expect("export toml");
+        let exported = export_config_toml(CONFIG_ID).expect("export toml");
         assert!(exported.toml_text.contains("instance_id"));
 
-        assert!(delete_config_record("cfg-1"));
-        assert!(get_config_record("cfg-1").is_none());
+        assert!(delete_config_record(CONFIG_ID));
+        assert!(get_config_record(CONFIG_ID).is_none());
     }
 
     #[test]
     fn set_config_field_updates_only_requested_top_level_field() {
+        const CONFIG_ID: &str = "00000000-0000-0000-0000-000000000002";
         let root = test_root();
         assert!(init_config_store(root));
 
-        let config_json = crate::build_default_network_config_json().expect("default config");
+        let config_json = get_default_config_json().expect("default config");
         save_config_record(
-            "cfg-field".to_string(),
+            CONFIG_ID.to_string(),
             "field-config".to_string(),
             config_json,
         )
         .expect("save config");
 
-        let before_network_name = get_config_field_value("cfg-field", "network_name");
-        let before_instance_id = get_config_field_value("cfg-field", "instance_id")
+        let before_network_name = get_config_field_value(CONFIG_ID, "network_name");
+        let before_instance_id = get_config_field_value(CONFIG_ID, "instance_id")
             .expect("instance id field should exist");
 
         assert!(set_config_field_value(
-            "cfg-field",
+            CONFIG_ID,
             "network_name",
             "\"changed-network\""
         ));
 
         assert_eq!(
-            get_config_field_value("cfg-field", "network_name"),
+            get_config_field_value(CONFIG_ID, "network_name"),
             Some("\"changed-network\"".to_string())
         );
         assert_eq!(
-            get_config_field_value("cfg-field", "instance_id"),
+            get_config_field_value(CONFIG_ID, "instance_id"),
             Some(before_instance_id)
         );
         assert_ne!(
-            get_config_field_value("cfg-field", "network_name"),
+            get_config_field_value(CONFIG_ID, "network_name"),
             before_network_name
         );
     }

easytier-contrib/easytier-ohrs/crates/easytier-ohos-features/src/lib.rs

@@ -0,0 +1,81 @@
+use std::sync::OnceLock;
+
+#[derive(Clone, Copy)]
+pub struct FeatureLogSink {
+    pub enabled: fn(i32) -> bool,
+    pub emit: fn(i32, &str, &str),
+}
+
+static FEATURE_LOG_SINK: OnceLock<FeatureLogSink> = OnceLock::new();
+
+/// Installs the outer HAR facade's log sink without coupling this feature crate to N-API setup.
+pub fn install_log_sink(sink: FeatureLogSink) {
+    let _ = FEATURE_LOG_SINK.set(sink);
+}
+
+#[doc(hidden)]
+pub fn log_enabled(level: i32) -> bool {
+    FEATURE_LOG_SINK
+        .get()
+        .map(|sink| (sink.enabled)(level))
+        .unwrap_or(true)
+}
+
+#[doc(hidden)]
+pub fn emit_log(level: i32, message: String) {
+    if let Some(sink) = FEATURE_LOG_SINK.get() {
+        (sink.emit)(level, "RustOhrs", &message);
+        return;
+    }
+    match level {
+        5 => tracing::error!(target: "easytier_ohrs", "{message}"),
+        4 => tracing::info!(target: "easytier_ohrs", "{message}"),
+        _ => tracing::debug!(target: "easytier_ohrs", "{message}"),
+    }
+}
+
+macro_rules! ohrs_log_error {
+    ($($arg:tt)*) => {{
+        $crate::emit_log(5, std::format!($($arg)*));
+    }};
+}
+
+macro_rules! ohrs_log_debug {
+    ($($arg:tt)*) => {{
+        if $crate::log_enabled(3) {
+            $crate::emit_log(3, std::format!($($arg)*));
+        }
+    }};
+}
+
+pub mod config;
+
+#[cfg(test)]
+mod architecture_tests {
+    fn assert_no_napi_annotations(path: &std::path::Path) {
+        for entry in std::fs::read_dir(path).expect("read source directory") {
+            let path = entry.expect("read source entry").path();
+            if path.is_dir() {
+                assert_no_napi_annotations(&path);
+            } else if path.extension().is_some_and(|extension| extension == "rs") {
+                let source = std::fs::read_to_string(&path).expect("read Rust source");
+                let marker = ["#[", "napi"].concat();
+                assert!(!source.contains(&marker), "N-API annotation in {path:?}");
+            }
+        }
+    }
+
+    #[test]
+    fn inner_crate_has_no_napi_registration_dependency() {
+        let manifest = include_str!("../Cargo.toml");
+        let runtime_dependency = ["napi", "ohos"].join("-");
+        let derive_dependency = ["napi", "derive", "ohos"].join("-");
+        assert!(!manifest.contains(&runtime_dependency));
+        assert!(!manifest.contains(&derive_dependency));
+        assert_no_napi_annotations(
+            std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
+                .join("src")
+                .as_path(),
+        );
+    }
+}

easytier-contrib/easytier-ohrs/src/config.rs

@@ -1,4 +0,0 @@
-pub(crate) mod repository;
-pub(crate) mod services;
-pub(crate) mod storage;
-pub(crate) mod types;

easytier-contrib/easytier-ohrs/src/config/services/mod.rs

@@ -1,2 +0,0 @@
-pub(crate) mod schema_service;
-pub(crate) mod share_link_service;

easytier-contrib/easytier-ohrs/src/config/storage/mod.rs

@@ -1 +0,0 @@
-pub(crate) mod config_meta;

easytier-contrib/easytier-ohrs/src/config/types/mod.rs

@@ -1 +0,0 @@
-pub(crate) mod stored_config;

easytier-contrib/easytier-ohrs/src/exports/config_api.rs

@@ -2,6 +2,10 @@ use crate::config;
 use crate::config::types::stored_config::SnapshotImportResult;
 
 pub(crate) fn init_config_store(root_dir: String) -> bool {
+    easytier_ohos_features::install_log_sink(easytier_ohos_features::FeatureLogSink {
+        enabled: crate::feature_log_enabled,
+        emit: crate::feature_log_sink,
+    });
     config::repository::init_config_store(root_dir)
 }
 

easytier-contrib/easytier-ohrs/src/exports/runtime_api.rs

@@ -157,19 +157,10 @@ pub(crate) fn collect_runtime_state() -> RuntimeAggregateState {
                 .as_ref()
                 .map(|snapshot| snapshot.display_name.clone())
                 .unwrap_or_else(|| config_id.clone());
-            let magic_dns_enabled = snapshot
-                .as_ref()
-                .and_then(|snapshot| snapshot.config.enable_magic_dns)
-                .unwrap_or(false);
-            let need_exit_node = snapshot
-                .as_ref()
-                .map(|snapshot| !snapshot.config.exit_nodes.is_empty())
-                .unwrap_or(false);
             instances.push(runtime_instance_from_running_info(
                 config_id,
                 display_name,
-                magic_dns_enabled,
-                need_exit_node,
+                snapshot.map(|snapshot| snapshot.config),
                 info,
             ));
         } else if let Some(snapshot) = get_runtime_config_snapshot(&config_id) {
@@ -195,6 +186,7 @@ pub(crate) fn collect_runtime_state() -> RuntimeAggregateState {
                 events: Vec::new(),
                 routes: Vec::new(),
                 peers: Vec::new(),
+                manual_routes: Vec::new(),
             });
         }
     }

easytier-contrib/easytier-ohrs/src/kernel_bridge.rs

@@ -1,6 +1,4 @@
-mod protocol;
-mod routing;
 mod socket_server;
 
-pub(crate) use routing::aggregate_requested_tun_routes;
+pub(crate) use easytier_ohos_core::routing::aggregate_requested_tun_routes;
 pub use socket_server::{start_local_socket_server, stop_local_socket_server};

easytier-contrib/easytier-ohrs/src/kernel_bridge/socket_server.rs

@@ -1,15 +1,15 @@
-use super::protocol::{
-    TunRequestPayload, broadcast_local_socket_json_payload_message, broadcast_local_socket_message,
-};
 use crate::collect_runtime_state_inner;
 use crate::config::repository::kernel_socket_path;
-use crate::kernel_bridge::routing::aggregate_tun_routes;
 use crate::runtime::state::runtime_state::{
     PeerConnInfo as RuntimePeerConnInfo, RuntimeAggregateState, peer_conn_to_view,
 };
 use crate::{ASYNC_RUNTIME, INSTANCE_MANAGER};
 use easytier::common::global_ctx::{EventBusSubscriber, GlobalCtxEvent};
 use easytier::instance::factory::subscribe_native_instance_event;
+use easytier_ohos_core::protocol::{
+    TunRequestPayload, broadcast_local_socket_json_payload_message, broadcast_local_socket_message,
+};
+use easytier_ohos_core::routing::aggregate_tun_routes;
 use once_cell::sync::Lazy;
 use serde::Serialize;
 use std::collections::{HashMap, HashSet};

easytier-contrib/easytier-ohrs/src/lib.rs

@@ -22,28 +22,14 @@ macro_rules! ohrs_log_info {
     }};
 }
 
-macro_rules! ohrs_log_debug {
-    ($($arg:tt)*) => {{
-        if $crate::platform::logging::log_manager::app_log_enabled(3) {
-            $crate::platform::logging::log_manager::record_app_log(
-                3,
-                "RustOhrs",
-                &std::format!($($arg)*),
-            );
-        }
-    }};
-}
-
-mod config;
 mod exports;
 mod kernel_bridge;
+mod napi_types;
 mod nearby_management;
 mod platform;
-mod runtime;
 
-use config::repository::{cache_runtime_config_snapshot, start_kernel_with_config_id};
+use config::repository::cache_runtime_config_snapshot;
 use config::services::schema_service::{
-    ConfigFieldMapping, NetworkConfigSchema,
     get_network_config_field_mappings as build_network_config_field_mappings,
     get_network_config_schema as build_network_config_schema,
 };
@@ -53,43 +39,42 @@ use config::services::share_link_service::{
     parse_config_share_link as parse_config_share_link_inner,
 };
 use config::storage::config_meta::get_config_display_name;
-use config::types::stored_config::{KeyValuePair, SharedConfigLinkPayload, SnapshotImportResult};
 use easytier::common::config::NetworkConfigExt;
 use easytier::common::constants::EASYTIER_VERSION;
 use easytier::common::{
     MachineIdOptions,
     config::{ConfigLoader, TomlConfigLoader},
 };
-use easytier::instance::factory::{NativeInstanceManager, native_instance_manager_with_runtime};
 use easytier::proto::api::manage::NetworkConfig;
 use easytier::proto::api::manage::NetworkingMethod;
-use easytier::proto::common::CompressionAlgoPb;
 use easytier::web_client::{WebClient, WebClientHooks, run_web_client};
+use easytier_ohos_core::runtime;
+use easytier_ohos_core::{ASYNC_RUNTIME, INSTANCE_MANAGER};
+use easytier_ohos_features::config;
 use kernel_bridge::{
     start_local_socket_server as start_local_socket_server_inner,
     stop_local_socket_server as stop_local_socket_server_inner,
 };
 use napi_derive_ohos::napi;
 use napi_ohos::bindgen_prelude::Uint8Array;
+use napi_types::{
+    ConfigFieldMapping, KeyValuePair, NetworkConfigSchema, SharedConfigLinkPayload,
+    SnapshotImportResult, SocketProtectionRequest,
+};
 use runtime::state::runtime_state::{RuntimeAggregateState, RuntimeInstanceState};
 use std::collections::{HashMap, HashSet};
 use std::format;
 use std::sync::{Arc, Mutex};
-use tokio::runtime::{Builder, Runtime};
 use uuid::Uuid;
 
-static ASYNC_RUNTIME: once_cell::sync::Lazy<Runtime> = once_cell::sync::Lazy::new(|| {
-    Builder::new_multi_thread()
-        .enable_all()
-        .build()
-        .expect("tokio runtime for easytier-ohrs")
-});
-pub(crate) static INSTANCE_MANAGER: once_cell::sync::Lazy<Arc<NativeInstanceManager>> =
-    once_cell::sync::Lazy::new(|| {
-        Arc::new(native_instance_manager_with_runtime(
-            ASYNC_RUNTIME.handle().clone(),
-        ))
-    });
+pub(crate) fn feature_log_sink(level: i32, target: &str, message: &str) {
+    platform::logging::log_manager::record_app_log(level, target, message);
+}
+
+pub(crate) fn feature_log_enabled(level: i32) -> bool {
+    platform::logging::log_manager::app_log_enabled(level)
+}
+
 static WEB_CLIENTS: once_cell::sync::Lazy<Mutex<HashMap<String, ManagedWebClient>>> =
     once_cell::sync::Lazy::new(|| Mutex::new(HashMap::new()));
 const PRO_CONFIG_SERVER_CLIENT_ID: &str = "__easytier_pro_config_server_client__";
@@ -669,15 +654,6 @@ fn resolve_instance_id_inner(instance_name: &str) -> Option<String> {
     resolve_instance_id_from_state(&collect_runtime_state_inner(), instance_name)
 }
 
-pub(crate) fn build_default_network_config_json() -> Result<String, String> {
-    let mut config = NetworkConfig::new_from_config(TomlConfigLoader::default())
-        .map_err(|e| format!("default_network_config failed {}", e))?;
-    // HarmonyOS 的配置编辑页将压缩算法作为显式选项展示。新建实例默认
-    // 使用 NONE，避免在用户没有主动选择时增加压缩开销。
-    config.data_compress_algo = Some(CompressionAlgoPb::None as i32);
-    serde_json::to_string(&config).map_err(|e| format!("default_network_config failed {}", e))
-}
-
 fn convert_toml_to_network_config_inner(toml_text: &str) -> Result<String, String> {
     let config = NetworkConfig::new_from_config(
         TomlConfigLoader::new_from_str(toml_text).map_err(|e| e.to_string())?,
@@ -754,6 +730,18 @@ pub(crate) fn run_network_instance_from_json(cfg_json: &str) -> bool {
     }
 }
 
+fn start_kernel_with_config_id(config_id: &str) -> bool {
+    let Some(raw) = config::repository::load_config_json(config_id) else {
+        return false;
+    };
+    let display_name = get_config_display_name(config_id).unwrap_or_else(|| config_id.to_string());
+    let started = run_network_instance_from_json(&raw);
+    if started && let Ok(config) = serde_json::from_str::<NetworkConfig>(&raw) {
+        cache_runtime_config_snapshot(config_id.to_string(), display_name, config);
+    }
+    started
+}
+
 fn parse_instance_uuid(config_id: &str) -> Option<Uuid> {
     match Uuid::parse_str(config_id) {
         Ok(uuid) => Some(uuid),
@@ -851,7 +839,7 @@ pub fn import_config_store_snapshot(source_path: String) -> bool {
 
 #[napi]
 pub fn import_config_store_snapshot_with_result(source_path: String) -> SnapshotImportResult {
-    exports::config_api::import_config_store_snapshot_with_result(source_path)
+    exports::config_api::import_config_store_snapshot_with_result(source_path).into()
 }
 
 #[napi]
@@ -1060,6 +1048,9 @@ pub async fn call_nearby_management_json_rpc(
 #[napi]
 pub fn collect_network_infos() -> Vec<KeyValuePair> {
     exports::runtime_api::collect_network_infos()
+        .into_iter()
+        .map(Into::into)
+        .collect()
 }
 
 #[napi]
@@ -1067,14 +1058,53 @@ pub fn set_tun_fd(config_id: String, fd: i32) -> bool {
     exports::runtime_api::set_tun_fd(config_id, fd, parse_instance_uuid)
 }
 
+#[napi]
+pub fn enable_socket_protection() -> bool {
+    easytier_ohos_core::socket_protection::enable_socket_protection()
+}
+
+#[napi]
+pub async fn next_socket_protection_request() -> Option<SocketProtectionRequest> {
+    easytier_ohos_core::socket_protection::SOCKET_PROTECTION_MANAGER
+        .next_request()
+        .await
+        .map(Into::into)
+}
+
+#[napi]
+pub fn complete_socket_protection(
+    request_id: String,
+    success: bool,
+    error: Option<String>,
+) -> bool {
+    let Ok(request_id) = request_id.parse::<u64>() else {
+        return false;
+    };
+    easytier_ohos_core::socket_protection::SOCKET_PROTECTION_MANAGER
+        .complete_request(request_id, success, error)
+}
+
+#[napi]
+pub fn disable_socket_protection() -> bool {
+    easytier_ohos_core::socket_protection::disable_socket_protection()
+}
+
+#[napi]
+pub fn fail_socket_protection() -> bool {
+    easytier_ohos_core::socket_protection::fail_socket_protection()
+}
+
 #[napi]
 pub fn get_network_config_schema() -> NetworkConfigSchema {
-    build_network_config_schema()
+    build_network_config_schema().into()
 }
 
 #[napi]
 pub fn get_network_config_field_mappings() -> Vec<ConfigFieldMapping> {
     build_network_config_field_mappings()
+        .into_iter()
+        .map(Into::into)
+        .collect()
 }
 
 #[cfg(test)]
@@ -1122,6 +1152,7 @@ mod tests {
                     events: vec![],
                     routes: vec![],
                     peers: vec![],
+                    manual_routes: vec![],
                 },
                 RuntimeInstanceState {
                     config_id: "ec7b6a3c-aeae-4c0e-844e-f7ec2dbdc2ce".to_string(),
@@ -1137,6 +1168,7 @@ mod tests {
                     events: vec![],
                     routes: vec![],
                     peers: vec![],
+                    manual_routes: vec![],
                 },
             ],
             tun: runtime::state::runtime_state::TunAggregateState {
@@ -1203,7 +1235,7 @@ pub fn build_config_share_link(config_id: String, only_start: Option<bool>) -> O
 
 #[napi]
 pub fn parse_config_share_link(share_link: String) -> Option<SharedConfigLinkPayload> {
-    parse_config_share_link_inner(&share_link)
+    parse_config_share_link_inner(&share_link).map(Into::into)
 }
 
 #[napi]

easytier-contrib/easytier-ohrs/src/napi_types.rs

@@ -0,0 +1,492 @@
+#![allow(dead_code)]
+
+use easytier_ohos_core::runtime::state::runtime_state as kernel_types;
+use easytier_ohos_features::config::services::schema_service as feature_schema;
+use easytier_ohos_features::config::types::stored_config as feature_types;
+use napi_derive_ohos::napi;
+use serde::Serialize;
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+#[napi(object)]
+pub struct SocketProtectionRequest {
+    pub request_id: String,
+    pub socket_fd: i32,
+    pub purpose: String,
+}
+
+impl From<easytier_ohos_core::socket_protection::SocketProtectionRequest>
+    for SocketProtectionRequest
+{
+    fn from(value: easytier_ohos_core::socket_protection::SocketProtectionRequest) -> Self {
+        Self {
+            request_id: value.request_id.to_string(),
+            socket_fd: value.socket_fd,
+            purpose: value.purpose,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+#[napi(object)]
+pub struct StoredConfigMeta {
+    pub config_id: String,
+    pub display_name: String,
+    pub created_at: String,
+    pub updated_at: String,
+    pub favorite: bool,
+    pub temporary: bool,
+}
+
+impl From<feature_types::StoredConfigMeta> for StoredConfigMeta {
+    fn from(value: feature_types::StoredConfigMeta) -> Self {
+        Self {
+            config_id: value.config_id,
+            display_name: value.display_name,
+            created_at: value.created_at,
+            updated_at: value.updated_at,
+            favorite: value.favorite,
+            temporary: value.temporary,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+#[napi(object)]
+pub struct StoredConfigRecord {
+    pub meta: StoredConfigMeta,
+    pub config_json: String,
+}
+
+impl From<feature_types::StoredConfigRecord> for StoredConfigRecord {
+    fn from(value: feature_types::StoredConfigRecord) -> Self {
+        Self {
+            meta: value.meta.into(),
+            config_json: value.config_json,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+#[napi(object)]
+pub struct StoredConfigList {
+    pub configs: Vec<StoredConfigMeta>,
+}
+
+impl From<feature_types::StoredConfigList> for StoredConfigList {
+    fn from(value: feature_types::StoredConfigList) -> Self {
+        Self {
+            configs: value.configs.into_iter().map(Into::into).collect(),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+#[napi(object)]
+pub struct ExportTomlResult {
+    pub toml_text: String,
+}
+
+impl From<feature_types::ExportTomlResult> for ExportTomlResult {
+    fn from(value: feature_types::ExportTomlResult) -> Self {
+        Self {
+            toml_text: value.toml_text,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+#[napi(object)]
+pub struct SharedConfigLinkPayload {
+    pub config_json: String,
+    pub display_name: Option<String>,
+    pub only_start: bool,
+}
+
+impl From<feature_types::SharedConfigLinkPayload> for SharedConfigLinkPayload {
+    fn from(value: feature_types::SharedConfigLinkPayload) -> Self {
+        Self {
+            config_json: value.config_json,
+            display_name: value.display_name,
+            only_start: value.only_start,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+#[napi(object)]
+pub struct LocalSocketSyncMessage {
+    pub message_type: String,
+    pub payload_json: String,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[napi(object)]
+pub struct KeyValuePair {
+    pub key: String,
+    pub value: String,
+}
+
+impl From<feature_types::KeyValuePair> for KeyValuePair {
+    fn from(value: feature_types::KeyValuePair) -> Self {
+        Self {
+            key: value.key,
+            value: value.value,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+#[napi(object)]
+pub struct SnapshotImportResult {
+    pub ok: bool,
+    pub error_code: String,
+    pub error_message: String,
+    pub snapshot_invalid: bool,
+}
+
+impl From<feature_types::SnapshotImportResult> for SnapshotImportResult {
+    fn from(value: feature_types::SnapshotImportResult) -> Self {
+        Self {
+            ok: value.ok,
+            error_code: value.error_code,
+            error_message: value.error_message,
+            snapshot_invalid: value.snapshot_invalid,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[napi(object)]
+pub struct FieldOption {
+    pub label: String,
+    pub value: String,
+}
+
+impl From<feature_schema::FieldOption> for FieldOption {
+    fn from(value: feature_schema::FieldOption) -> Self {
+        Self {
+            label: value.label,
+            value: value.value,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[napi(object)]
+pub struct ValidationRule {
+    pub rule_type: String,
+    pub arg: String,
+    pub message: String,
+}
+
+impl From<feature_schema::ValidationRule> for ValidationRule {
+    fn from(value: feature_schema::ValidationRule) -> Self {
+        Self {
+            rule_type: value.rule_type,
+            arg: value.arg,
+            message: value.message,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[napi(object)]
+pub struct NetworkConfigSchema {
+    pub node_kind: String,
+    pub name: String,
+    pub field_number: i32,
+    pub type_name: Option<String>,
+    pub semantic_type: Option<String>,
+    pub value_kind: String,
+    pub is_list: bool,
+    pub required: bool,
+    pub default_value_text: Option<String>,
+    pub enum_options: Vec<FieldOption>,
+    pub validations: Vec<ValidationRule>,
+    pub children: Vec<NetworkConfigSchema>,
+    pub definitions: Vec<NetworkConfigSchema>,
+}
+
+impl From<feature_schema::NetworkConfigSchema> for NetworkConfigSchema {
+    fn from(value: feature_schema::NetworkConfigSchema) -> Self {
+        Self {
+            node_kind: value.node_kind,
+            name: value.name,
+            field_number: value.field_number,
+            type_name: value.type_name,
+            semantic_type: value.semantic_type,
+            value_kind: value.value_kind,
+            is_list: value.is_list,
+            required: value.required,
+            default_value_text: value.default_value_text,
+            enum_options: value.enum_options.into_iter().map(Into::into).collect(),
+            validations: value.validations.into_iter().map(Into::into).collect(),
+            children: value.children.into_iter().map(Into::into).collect(),
+            definitions: value.definitions.into_iter().map(Into::into).collect(),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[napi(object)]
+pub struct ConfigFieldMapping {
+    pub field_name: String,
+    pub field_number: i32,
+}
+
+impl From<feature_schema::ConfigFieldMapping> for ConfigFieldMapping {
+    fn from(value: feature_schema::ConfigFieldMapping) -> Self {
+        Self {
+            field_name: value.field_name,
+            field_number: value.field_number,
+        }
+    }
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+#[napi(object)]
+pub struct PeerConnStats {
+    pub rx_bytes: i64,
+    pub tx_bytes: i64,
+    pub rx_packets: i64,
+    pub tx_packets: i64,
+    pub latency_us: i64,
+}
+
+impl From<kernel_types::PeerConnStats> for PeerConnStats {
+    fn from(value: kernel_types::PeerConnStats) -> Self {
+        Self {
+            rx_bytes: value.rx_bytes,
+            tx_bytes: value.tx_bytes,
+            rx_packets: value.rx_packets,
+            tx_packets: value.tx_packets,
+            latency_us: value.latency_us,
+        }
+    }
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+#[napi(object)]
+pub struct PeerConnInfo {
+    pub conn_id: String,
+    pub my_peer_id: i64,
+    pub peer_id: i64,
+    pub features: Vec<String>,
+    pub tunnel_type: Option<String>,
+    pub local_addr: Option<String>,
+    pub remote_addr: Option<String>,
+    pub resolved_remote_addr: Option<String>,
+    pub stats: Option<PeerConnStats>,
+    pub loss_rate: Option<f64>,
+    pub is_client: bool,
+    pub network_name: Option<String>,
+    pub is_closed: bool,
+    pub secure_auth_level: Option<i32>,
+    pub peer_identity_type: Option<i32>,
+}
+
+impl From<kernel_types::PeerConnInfo> for PeerConnInfo {
+    fn from(value: kernel_types::PeerConnInfo) -> Self {
+        Self {
+            conn_id: value.conn_id,
+            my_peer_id: value.my_peer_id,
+            peer_id: value.peer_id,
+            features: value.features,
+            tunnel_type: value.tunnel_type,
+            local_addr: value.local_addr,
+            remote_addr: value.remote_addr,
+            resolved_remote_addr: value.resolved_remote_addr,
+            stats: value.stats.map(Into::into),
+            loss_rate: value.loss_rate,
+            is_client: value.is_client,
+            network_name: value.network_name,
+            is_closed: value.is_closed,
+            secure_auth_level: value.secure_auth_level,
+            peer_identity_type: value.peer_identity_type,
+        }
+    }
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+#[napi(object)]
+pub struct PeerInfo {
+    pub peer_id: i64,
+    pub default_conn_id: Option<String>,
+    pub directly_connected_conns: Vec<String>,
+    pub conns: Vec<PeerConnInfo>,
+}
+
+impl From<kernel_types::PeerInfo> for PeerInfo {
+    fn from(value: kernel_types::PeerInfo) -> Self {
+        Self {
+            peer_id: value.peer_id,
+            default_conn_id: value.default_conn_id,
+            directly_connected_conns: value.directly_connected_conns,
+            conns: value.conns.into_iter().map(Into::into).collect(),
+        }
+    }
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+#[napi(object)]
+pub struct RouteView {
+    pub peer_id: i64,
+    pub hostname: Option<String>,
+    pub ipv4: Option<String>,
+    pub ipv4_cidr: Option<String>,
+    pub ipv6_cidr: Option<String>,
+    pub proxy_cidrs: Vec<String>,
+    pub next_hop_peer_id: Option<i64>,
+    pub cost: Option<i32>,
+    pub path_latency: Option<i64>,
+    pub udp_nat_type: Option<i32>,
+    pub tcp_nat_type: Option<i32>,
+    pub inst_id: Option<String>,
+    pub version: Option<String>,
+    pub is_public_server: Option<bool>,
+}
+
+impl From<kernel_types::RouteView> for RouteView {
+    fn from(value: kernel_types::RouteView) -> Self {
+        Self {
+            peer_id: value.peer_id,
+            hostname: value.hostname,
+            ipv4: value.ipv4,
+            ipv4_cidr: value.ipv4_cidr,
+            ipv6_cidr: value.ipv6_cidr,
+            proxy_cidrs: value.proxy_cidrs,
+            next_hop_peer_id: value.next_hop_peer_id,
+            cost: value.cost,
+            path_latency: value.path_latency,
+            udp_nat_type: value.udp_nat_type,
+            tcp_nat_type: value.tcp_nat_type,
+            inst_id: value.inst_id,
+            version: value.version,
+            is_public_server: value.is_public_server,
+        }
+    }
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+#[napi(object)]
+pub struct MyNodeInfo {
+    pub virtual_ipv4: Option<String>,
+    pub virtual_ipv4_cidr: Option<String>,
+    pub hostname: Option<String>,
+    pub version: Option<String>,
+    pub peer_id: Option<i64>,
+    pub listeners: Vec<String>,
+    pub vpn_portal_cfg: Option<String>,
+    pub udp_nat_type: Option<i32>,
+    pub tcp_nat_type: Option<i32>,
+}
+
+impl From<kernel_types::MyNodeInfo> for MyNodeInfo {
+    fn from(value: kernel_types::MyNodeInfo) -> Self {
+        Self {
+            virtual_ipv4: value.virtual_ipv4,
+            virtual_ipv4_cidr: value.virtual_ipv4_cidr,
+            hostname: value.hostname,
+            version: value.version,
+            peer_id: value.peer_id,
+            listeners: value.listeners,
+            vpn_portal_cfg: value.vpn_portal_cfg,
+            udp_nat_type: value.udp_nat_type,
+            tcp_nat_type: value.tcp_nat_type,
+        }
+    }
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+#[napi(object)]
+pub struct RuntimeInstanceState {
+    pub config_id: String,
+    pub instance_id: String,
+    pub display_name: String,
+    pub running: bool,
+    pub tun_required: bool,
+    pub tun_attached: bool,
+    pub magic_dns_enabled: bool,
+    pub need_exit_node: bool,
+    pub error_message: Option<String>,
+    pub my_node_info: Option<MyNodeInfo>,
+    pub events: Vec<String>,
+    pub routes: Vec<RouteView>,
+    pub peers: Vec<PeerInfo>,
+}
+
+impl From<kernel_types::RuntimeInstanceState> for RuntimeInstanceState {
+    fn from(value: kernel_types::RuntimeInstanceState) -> Self {
+        Self {
+            config_id: value.config_id,
+            instance_id: value.instance_id,
+            display_name: value.display_name,
+            running: value.running,
+            tun_required: value.tun_required,
+            tun_attached: value.tun_attached,
+            magic_dns_enabled: value.magic_dns_enabled,
+            need_exit_node: value.need_exit_node,
+            error_message: value.error_message,
+            my_node_info: value.my_node_info.map(Into::into),
+            events: value.events,
+            routes: value.routes.into_iter().map(Into::into).collect(),
+            peers: value.peers.into_iter().map(Into::into).collect(),
+        }
+    }
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+#[napi(object)]
+pub struct TunAggregateState {
+    pub active: bool,
+    pub attached_instance_ids: Vec<String>,
+    pub aggregated_routes: Vec<String>,
+    pub dns_servers: Vec<String>,
+    pub need_rebuild: bool,
+}
+
+impl From<kernel_types::TunAggregateState> for TunAggregateState {
+    fn from(value: kernel_types::TunAggregateState) -> Self {
+        Self {
+            active: value.active,
+            attached_instance_ids: value.attached_instance_ids,
+            aggregated_routes: value.aggregated_routes,
+            dns_servers: value.dns_servers,
+            need_rebuild: value.need_rebuild,
+        }
+    }
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+#[napi(object)]
+pub struct RuntimeAggregateState {
+    pub instances: Vec<RuntimeInstanceState>,
+    pub tun: TunAggregateState,
+    pub running_instance_count: i32,
+}
+
+impl From<kernel_types::RuntimeAggregateState> for RuntimeAggregateState {
+    fn from(value: kernel_types::RuntimeAggregateState) -> Self {
+        Self {
+            instances: value.instances.into_iter().map(Into::into).collect(),
+            tun: value.tun.into(),
+            running_instance_count: value.running_instance_count,
+        }
+    }
+}

easytier-contrib/easytier-ohrs/src/runtime.rs

@@ -1 +0,0 @@
-pub(crate) mod state;

easytier-contrib/easytier-ohrs/src/runtime/state/mod.rs

@@ -1 +0,0 @@
-pub(crate) mod runtime_state;

easytier-contrib/easytier-uptime/Cargo.toml

@@ -4,24 +4,22 @@ version = "0.1.0"
 edition.workspace = true
 
 [dependencies]
-tokio = { version = "1.0", features = ["full"] }
-tracing = "0.1"
-tracing-subscriber = { version = "0.3", features = ["env-filter"] }
-anyhow = "1.0"
-serde = { version = "1.0", features = ["derive"] }
-serde_json = "1.0"
-chrono = { version = "0.4", features = ["serde"] }
-uuid = { version = "1.0", features = ["v4", "serde"] }
-guarden = "0.1"
+tokio = { workspace = true, default-features = true, features = ["full"] }
+tracing.workspace = true
+tracing-subscriber = { workspace = true, default-features = true, features = ["env-filter"] }
+anyhow.workspace = true
+serde = { workspace = true, features = ["derive"] }
+serde_json.workspace = true
+chrono = { workspace = true, features = ["serde"] }
+uuid = { workspace = true, features = ["v4", "serde"] }
 
 # Axum web framework
-axum = { version = "0.8.4", features = ["macros"] }
-axum-extra = { version = "0.10", features = ["query"] }
-tower-http = { version = "0.6", features = ["cors", "compression-full"] }
-tower = "0.5"
+axum = { version = "0.8.9", features = ["macros"] }
+axum-extra = { version = "0.12", features = ["query"] }
+tower-http = { workspace = true, features = ["cors", "compression-full"] }
 
 # SeaORM dependencies
-sea-orm = { version = "1.1", features = [
+sea-orm = { workspace = true, features = [
     "sqlx-sqlite",
     "runtime-tokio-rustls",
     "macros",
@@ -29,39 +27,23 @@ sea-orm = { version = "1.1", features = [
     "with-uuid",
     "with-json"
 ] }
-sea-orm-migration = { version = "1.1" }
-sqlx = { version = "0.8", features = ["sqlite", "runtime-tokio-rustls", "chrono", "uuid"] }
+sea-orm-migration.workspace = true
+sqlx = { workspace = true, features = ["sqlite", "runtime-tokio-rustls", "chrono", "uuid"] }
 
 # Validation
-validator = { version = "0.18", features = ["derive"] }
-thiserror = "1.0"
-jsonwebtoken = "9.0"
-
-# Configuration and serialization
-serde_yaml = "0.9"
-toml = "0.8"
+validator = { version = "0.21", features = ["derive"] }
+thiserror.workspace = true
+jsonwebtoken = { version = "11.0", features = ["rust_crypto"] }
 
 # Network and async
-async-trait = "0.1"
-futures = "0.3"
-tokio-util = { version = "0.7", features = ["full"] }
-
-# Filesystem operations
-tempfile = "3.8"
+async-trait.workspace = true
+tokio-util = { workspace = true, features = ["full"] }
 
 # Additional utilities
-dashmap = "6.1.0"
-clap = { version = "4.0", features = ["derive"] }
-parking_lot = "0.12"
-once_cell = "1.19"
+dashmap.workspace = true
+clap = { workspace = true, features = ["derive"] }
 
 # EasyTier core
-easytier = { path = "../../easytier" }
+easytier = { workspace = true, default-features = true }
 
-mimalloc = { version = "*" }
-
-# Testing
-[dev-dependencies]
-mockall = "0.12"
-tokio-test = "0.4"
-reqwest = "0.12"
+mimalloc.workspace = true

easytier-contrib/easytier-uptime/src/db/operations.rs

@@ -383,7 +383,14 @@ mod tests {
         assert_eq!(node.name, "Test Node");
         assert_eq!(node.host, "test.example.com");
         assert_eq!(node.port, 11010);
+        assert!(!node.is_active);
+        assert!(!node.is_approved);
+
+        let node = NodeOperations::update_node_status(&db, node.id, true, Some(1))
+            .await
+            .unwrap();
         assert!(node.is_active);
+        assert_eq!(node.current_connections, 1);
 
         // 测试获取节点
         let found_node = NodeOperations::get_node_by_id(&db, node.id).await.unwrap();

easytier-core/Cargo.toml

@@ -3,7 +3,7 @@ name = "easytier-core"
 description = "EasyTier OS-free control-plane core primitives."
 homepage = "https://github.com/EasyTier/EasyTier"
 repository = "https://github.com/EasyTier/EasyTier"
-version = "2.6.4"
+version = "2.7.0"
 edition.workspace = true
 rust-version.workspace = true
 authors = ["kkrainbow"]
@@ -18,76 +18,76 @@ crate-type = ["rlib", "cdylib"]
 wasm-opt = ["-Oz", "--enable-bulk-memory", "--enable-nontrapping-float-to-int"]
 
 [dependencies]
-anyhow = "1.0"
-ariadne = { version = "0.5", optional = true }
-arc-swap = "1.7"
-async-ringbuf = "0.3.1"
-async-trait = "0.1.74"
-auto_impl = "1.1.0"
-base64 = "0.22"
-bitflags = "2.5"
-bytecodec = "0.4.15"
-bytes = "1.5.0"
-chrono = { version = "0.4.37", features = ["clock"] }
-cidr = { version = "0.3.1", features = ["serde"] }
-crossbeam = "0.8.4"
-dashmap = "6.0"
-derive_builder = "0.20.2"
-easytier-proto = { path = "../easytier-proto", default-features = false, features = ["core"] }
-futures = "0.3"
-guarden = "0.2"
-hmac = "0.12.1"
-http-body-util = { version = "0.1", optional = true }
-hyper = { version = "1", default-features = false, features = ["client", "http1"], optional = true }
-hyper-util = { version = "0.1", default-features = false, features = ["tokio"], optional = true }
-idna = "1.0"
-atomic-shim = "0.2.0"
-ordered_hash_map = "0.5.0"
-parking_lot = "0.12.1"
-percent-encoding = "2.3.1"
-petgraph = "0.8.1"
-pin-project-lite = "0.2.13"
-prefix-trie = { version = "0.7.0", features = ["cidr"] }
-prost = "0.14.3"
-prost-types = "0.14.3"
-rand = "0.8.5"
-quanta = "0.12"
+anyhow.workspace = true
+ariadne = { version = "0.6", optional = true }
+arc-swap.workspace = true
+async-ringbuf = "0.3.9"
+async-trait.workspace = true
+auto_impl.workspace = true
+base64.workspace = true
+bitflags = "2.13"
+bytecodec.workspace = true
+bytes.workspace = true
+chrono = { workspace = true, features = ["clock"] }
+cidr = { workspace = true, features = ["serde"] }
+crossbeam.workspace = true
+dashmap.workspace = true
+bon.workspace = true
+easytier-proto = { workspace = true, features = ["core"] }
+futures.workspace = true
+guarden.workspace = true
+hmac.workspace = true
+http-body-util = { workspace = true, optional = true }
+hyper = { workspace = true, features = ["client", "http1"], optional = true }
+hyper-util = { workspace = true, features = ["tokio"], optional = true }
+idna = "1.1"
+atomic-shim.workspace = true
+ordered_hash_map = "0.6.1"
+parking_lot.workspace = true
+percent-encoding.workspace = true
+petgraph = "0.8.3"
+pin-project-lite.workspace = true
+prefix-trie = { version = "0.10.1", features = ["cidr"] }
+prost.workspace = true
+prost-types.workspace = true
+rand.workspace = true
+quanta.workspace = true
 ring = { version = "0.17", optional = true }
-rustls = { version = "0.23", default-features = false, features = ["ring", "std", "tls12"], optional = true }
-serde = { version = "1.0", features = ["derive"] }
-serde_json = "1"
-sha2 = "0.10.8"
-smoltcp = { git = "https://github.com/smoltcp-rs/smoltcp.git", rev = "0a926767a68bc88d5512afefa7529c5ecdade4ea", optional = true, default-features = false }
-stun_codec = "0.3.4"
-thiserror = "1.0"
-tracing = "0.1"
-strum = { version = "0.27.2", features = ["derive"] }
-toml = "0.8.12"
-tokio = { version = "1", default-features = false, features = [
+rustls = { workspace = true, features = ["ring", "std", "tls12"], optional = true }
+serde = { workspace = true, features = ["derive"] }
+serde_json.workspace = true
+sha2.workspace = true
+smoltcp = { workspace = true, optional = true }
+stun_codec.workspace = true
+thiserror.workspace = true
+tracing.workspace = true
+strum = { workspace = true, features = ["derive"] }
+toml.workspace = true
+tokio = { workspace = true, features = [
     "rt",
     "time",
     "sync",
     "macros",
     "io-util",
 ] }
-tokio-util = { version = "0.7", features = ["io", "rt"] }
-tokio-rustls = { version = "0.26", default-features = false, optional = true }
-url = { version = "2.5", features = ["serde"] }
-wildmatch = "2.3.4"
-uuid = { version = "1.5.0", features = ["v4", "fast-rng", "serde"] }
-webpki-roots = { version = "0.26", optional = true }
-x25519-dalek = { version = "2.0", features = ["static_secrets"] }
-zerocopy = { version = "0.7.32", features = ["derive", "simd"] }
-zstd = { version = "0.13", optional = true }
-aes-gcm = { version = "0.10.3", optional = true }
-chacha20poly1305 = { version = "0.10.1", optional = true }
+tokio-util = { workspace = true, features = ["io", "rt"] }
+tokio-rustls = { workspace = true, optional = true }
+url = { workspace = true, features = ["serde"] }
+wildmatch = "2.6.1"
+uuid = { workspace = true, features = ["v4", "fast-rng", "serde"] }
+webpki-roots = { version = "1.0", optional = true }
+x25519-dalek = { workspace = true, features = ["static_secrets"] }
+zerocopy = { workspace = true, features = ["derive", "simd"] }
+zstd = { version = "0.14", optional = true }
+aes-gcm = { version = "0.11.1", optional = true }
+chacha20poly1305 = { version = "0.11.0", optional = true }
 openssl = { version = "0.10", optional = true, features = ["vendored"] }
 
 [target.'cfg(all(target_arch = "wasm32", target_os = "unknown"))'.dependencies]
-getrandom-02 = { package = "getrandom", version = "0.2.15", features = ["js"] }
-getrandom-03 = { package = "getrandom", version = "0.3.2", features = ["wasm_js"] }
+getrandom-02 = { package = "getrandom", version = "0.2.17", features = ["js"] }
+getrandom-03 = { package = "getrandom", version = "0.3.4", features = ["wasm_js"] }
 snow = { version = "0.10.0", default-features = false, features = ["default-resolver", "default-resolver-crypto"] }
-uuid = { version = "1.5.0", features = ["js"] }
+uuid = { workspace = true, features = ["js"] }
 wasm-bindgen = "0.2"
 
 [target.'cfg(not(all(target_arch = "wasm32", target_os = "unknown")))'.dependencies]
@@ -146,9 +146,18 @@ proxy-smoltcp-stack = [
     "smoltcp/proto-ipv6",
     "smoltcp/async",
 ]
+wasm-host-tunnel = []
+wasm-host-tunnel-outbound = ["wasm-host-tunnel"]
 test-utils = []
 tracing-log = ["tracing/log"]
 zstd = ["dep:zstd"]
 
 [target.'cfg(not(target_os = "wasi"))'.dev-dependencies]
-tokio = { version = "1", default-features = false, features = ["rt-multi-thread"] }
+tokio = { workspace = true, features = ["rt-multi-thread"] }
+
+[package.metadata.cargo-machete]
+ignored = [
+    # Enable browser entropy backends for transitive rand/snow dependencies.
+    "getrandom-02",
+    "getrandom-03",
+]

easytier-core/src/config/api_input.rs

@@ -84,6 +84,120 @@ pub trait NetworkConfigExt {
     fn new_from_config(config: impl ConfigLoader) -> Result<NetworkConfig, anyhow::Error>;
 }
 
+#[cfg(all(
+    feature = "browser-config",
+    any(test, all(target_arch = "wasm32", target_os = "unknown"))
+))]
+const FORM_MANAGED_TOML_FIELDS: &[&str] = &[
+    "hostname",
+    "instance_id",
+    "ipv4",
+    "ipv6_public_addr_provider",
+    "ipv6_public_addr_auto",
+    "ipv6_public_addr_prefix",
+    "dhcp",
+    "network_identity",
+    "listeners",
+    "mapped_listeners",
+    "exit_nodes",
+    "peer",
+    "proxy_network",
+    "vpn_portal_config",
+    "routes",
+    "socks5_proxy",
+    "port_forward",
+    "secure_mode",
+    "acl",
+    "credential_file",
+    "managed_credentials",
+];
+
+#[cfg(all(
+    feature = "browser-config",
+    any(test, all(target_arch = "wasm32", target_os = "unknown"))
+))]
+const FORM_MANAGED_FLAG_FIELDS: &[&str] = &[
+    "latency_first",
+    "dev_name",
+    "use_smoltcp",
+    "enable_ipv6",
+    "enable_kcp_proxy",
+    "disable_kcp_input",
+    "enable_quic_proxy",
+    "disable_quic_input",
+    "disable_p2p",
+    "p2p_only",
+    "lazy_p2p",
+    "bind_device",
+    "socket_mark",
+    "no_tun",
+    "enable_exit_node",
+    "relay_all_peer_rpc",
+    "need_p2p",
+    "multi_thread",
+    "proxy_forward_by_system",
+    "enable_encryption",
+    "relay_network_whitelist",
+    "disable_tcp_hole_punching",
+    "disable_udp_hole_punching",
+    "disable_upnp",
+    "disable_relay_data",
+    "prefer_peer_relay",
+    "enable_udp_broadcast_relay",
+    "disable_sym_hole_punching",
+    "accept_dns",
+    "mtu",
+    "instance_recv_bps_limit",
+    "private_mode",
+    "encryption_algorithm",
+    "data_compress_algo",
+];
+
+#[cfg(all(
+    feature = "browser-config",
+    any(test, all(target_arch = "wasm32", target_os = "unknown"))
+))]
+pub(crate) fn merge_network_config_toml(
+    original_toml: &str,
+    config: &NetworkConfig,
+) -> Result<String, anyhow::Error> {
+    let generated_toml = config.gen_config()?.dump();
+    let mut original = toml::from_str::<toml::Table>(original_toml)
+        .context("failed to parse the original TOML document")?;
+    let mut generated = toml::from_str::<toml::Table>(&generated_toml)
+        .context("failed to parse the generated TOML document")?;
+
+    for (key, value) in original.iter() {
+        if key != "flags" && !FORM_MANAGED_TOML_FIELDS.contains(&key.as_str()) {
+            generated.insert(key.clone(), value.clone());
+        }
+    }
+    if !original.contains_key("instance_name") {
+        generated.remove("instance_name");
+    }
+
+    let mut merged_flags: toml::Table = original
+        .remove("flags")
+        .and_then(|value| value.try_into().ok())
+        .unwrap_or_default();
+    let generated_flags: toml::Table = generated
+        .remove("flags")
+        .and_then(|value| value.try_into().ok())
+        .unwrap_or_default();
+    for key in FORM_MANAGED_FLAG_FIELDS {
+        if let Some(value) = generated_flags.get(*key) {
+            merged_flags.insert((*key).to_owned(), value.clone());
+        } else {
+            merged_flags.remove(*key);
+        }
+    }
+    if !merged_flags.is_empty() {
+        generated.insert("flags".to_owned(), toml::Value::Table(merged_flags));
+    }
+
+    toml::to_string_pretty(&generated).context("failed to serialize the merged TOML document")
+}
+
 fn parse_peer(peer: &manage::NetworkPeerConfig) -> Result<Option<PeerConfig>, anyhow::Error> {
     let uri = peer.uri.trim();
     if uri.is_empty() {
@@ -825,4 +939,49 @@ mod tests {
 
         assert!(config.get_vpn_portal_config().is_none());
     }
+
+    #[cfg(feature = "browser-config")]
+    #[test]
+    fn browser_merge_preserves_fields_outside_the_shared_form() {
+        let original = r#"
+instance_name = "module-instance"
+rpc_portal = "0.0.0.0:15888"
+tcp_whitelist = ["22"]
+stun_servers = ["custom.example.com:3478"]
+
+[network_identity]
+network_name = "old-network"
+network_secret = "secret"
+
+[flags]
+default_protocol = "udp"
+disable_p2p = true
+"#;
+        let parsed = TomlConfigLoader::new_from_str(original).unwrap();
+        let mut network_config = NetworkConfig::new_from_config(&parsed).unwrap();
+        network_config.network_name = Some("edited-network".to_owned());
+        network_config.disable_p2p = Some(false);
+
+        let merged = merge_network_config_toml(original, &network_config).unwrap();
+        let merged: toml::Table = toml::from_str(&merged).unwrap();
+
+        assert_eq!(merged["instance_name"].as_str(), Some("module-instance"));
+        assert_eq!(merged["rpc_portal"].as_str(), Some("0.0.0.0:15888"));
+        assert_eq!(merged["tcp_whitelist"][0].as_str(), Some("22"));
+        assert_eq!(
+            merged["stun_servers"][0].as_str(),
+            Some("custom.example.com:3478")
+        );
+        assert_eq!(
+            merged["network_identity"]["network_name"].as_str(),
+            Some("edited-network")
+        );
+        assert_eq!(merged["flags"]["default_protocol"].as_str(), Some("udp"));
+        assert!(
+            !merged["flags"]
+                .as_table()
+                .unwrap()
+                .contains_key("disable_p2p")
+        );
+    }
 }

easytier-core/src/config/browser.rs

@@ -1,7 +1,7 @@
 use wasm_bindgen::prelude::*;
 
 use super::{
-    api_input::{NetworkConfig, NetworkConfigExt},
+    api_input::{NetworkConfig, NetworkConfigExt, merge_network_config_toml},
     toml::{ConfigLoader, TomlConfig},
 };
 
@@ -18,6 +18,12 @@ pub fn generate_config(config_json: &str) -> Result<String, JsValue> {
         .map_err(js_error)
 }
 
+#[wasm_bindgen]
+pub fn merge_config(original_toml: &str, config_json: &str) -> Result<String, JsValue> {
+    let config: NetworkConfig = serde_json::from_str(config_json).map_err(js_error)?;
+    merge_network_config_toml(original_toml, &config).map_err(js_error)
+}
+
 #[wasm_bindgen]
 pub fn parse_config(toml_config: &str) -> Result<String, JsValue> {
     let config = TomlConfig::new_from_str(toml_config)

easytier-core/src/config/mod.rs

@@ -119,13 +119,12 @@ pub fn normalize_secure_mode_config(
     match config.local_public_key.as_ref() {
         None => config.local_public_key = Some(generated_public_key),
         Some(configured_public_key) => {
-            let public_key = config.public_key()?;
-            let canonical_public_key = BASE64_STANDARD.encode(public_key.as_bytes());
-            if configured_public_key != &canonical_public_key {
+            config.public_key()?;
+            if configured_public_key != &generated_public_key {
                 anyhow::bail!(
                     "local public key {} does not match generated public key {}",
                     configured_public_key,
-                    canonical_public_key
+                    generated_public_key
                 );
             }
         }
@@ -748,6 +747,24 @@ mod tests {
         );
     }
 
+    #[test]
+    fn secure_mode_normalization_rejects_mismatched_public_key() {
+        let private_key = StaticSecret::from([7; 32]);
+        let other_public_key = PublicKey::from(&StaticSecret::from([9; 32]));
+        let error = normalize_secure_mode_config(common_pb::SecureModeConfig {
+            enabled: true,
+            local_private_key: Some(BASE64_STANDARD.encode(private_key.as_bytes())),
+            local_public_key: Some(BASE64_STANDARD.encode(other_public_key.as_bytes())),
+        })
+        .unwrap_err()
+        .to_string();
+
+        assert!(
+            error.contains("does not match generated public key"),
+            "{error}"
+        );
+    }
+
     #[test]
     fn disabled_secure_mode_does_not_validate_keys() {
         let config = common_pb::SecureModeConfig {

easytier-core/src/config/toml.rs

@@ -6,6 +6,7 @@ use std::{
     sync::{Arc, Mutex},
 };
 
+use super::normalize_secure_mode_config;
 pub use super::{EncryptionAlgorithm, gateway::PortForwardConfig};
 use anyhow::Context;
 #[cfg(feature = "rich-config-errors")]
@@ -427,11 +428,11 @@ pub struct ConsoleLoggerConfig {
     pub level: Option<String>,
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, derive_builder::Builder)]
+#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, bon::Builder)]
 pub struct LoggingConfig {
-    #[builder(setter(into, strip_option), default = None)]
+    #[builder(into)]
     pub file_logger: Option<FileLoggerConfig>,
-    #[builder(setter(into, strip_option), default = None)]
+    #[builder(into)]
     pub console_logger: Option<ConsoleLoggerConfig>,
 }
 
@@ -705,6 +706,12 @@ impl TomlConfig {
             Self::gen_flags(config.flags.clone().unwrap_or_default())
                 .context("failed to parse flags")?,
         );
+        config.secure_mode = config
+            .secure_mode
+            .take()
+            .map(normalize_secure_mode_config)
+            .transpose()
+            .context("failed to normalize [secure_mode] config")?;
         let has_network_identity = config.network_identity.is_some();
 
         let config = TomlConfig {
@@ -1271,7 +1278,7 @@ network_secret = "network-secret"
 
 [secure_mode]
 enabled = true
-local_private_key = "noise-private-key"
+local_private_key = "YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWE="
 
 [vpn_portal_config]
 wireguard_listen = "0.0.0.0:51820"
@@ -1293,7 +1300,7 @@ group_secret = "group-secret"
 
         let dumped = config.dump();
         assert!(dumped.contains("network-secret"));
-        assert!(dumped.contains("noise-private-key"));
+        assert!(dumped.contains("YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWE="));
         assert!(dumped.contains("wireguard-private-key"));
         assert!(dumped.contains("group-secret"));
         assert_eq!(
@@ -1305,7 +1312,7 @@ group_secret = "group-secret"
 
         let redacted = config.dump_redacted();
         assert!(!redacted.contains("network-secret"));
-        assert!(!redacted.contains("noise-private-key"));
+        assert!(!redacted.contains("YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWE="));
         assert!(!redacted.contains("wireguard-private-key"));
         assert!(!redacted.contains("group-secret"));
         assert_eq!(redacted.matches("<redacted>").count(), 4);
@@ -1396,6 +1403,7 @@ source = "web"
 #[cfg(test)]
 mod compatibility_tests {
     use super::*;
+    use base64::{Engine as _, prelude::BASE64_STANDARD};
 
     #[cfg(feature = "config-write")]
     #[test]
@@ -1649,6 +1657,112 @@ enabled = true
         assert!(identity.network_secret_digest.is_some());
     }
 
+    #[test]
+    fn test_toml_secure_mode_generates_keypair_when_keys_missing() {
+        let config = TomlConfigLoader::new_from_str(
+            r#"
+[secure_mode]
+enabled = true
+"#,
+        )
+        .unwrap();
+
+        let secure_mode = config.get_secure_mode().unwrap();
+        let private_key = secure_mode.private_key().unwrap();
+        let public_key = secure_mode.public_key().unwrap();
+        assert_eq!(
+            x25519_dalek::PublicKey::from(&private_key).as_bytes(),
+            public_key.as_bytes()
+        );
+    }
+
+    #[test]
+    fn test_toml_secure_mode_derives_public_key_from_private_key() {
+        let private = x25519_dalek::StaticSecret::random_from_rng(rand::rngs::OsRng);
+        let config = TomlConfigLoader::new_from_str(&format!(
+            r#"
+[secure_mode]
+enabled = true
+local_private_key = "{}"
+"#,
+            BASE64_STANDARD.encode(private.as_bytes())
+        ))
+        .unwrap();
+
+        let secure_mode = config.get_secure_mode().unwrap();
+        let private_key = secure_mode.private_key().unwrap();
+        assert_eq!(private_key.as_bytes(), private.as_bytes());
+        assert_eq!(
+            secure_mode.public_key().unwrap().as_bytes(),
+            x25519_dalek::PublicKey::from(&private).as_bytes()
+        );
+    }
+
+    #[test]
+    fn test_toml_secure_mode_rejects_mismatched_keypair() {
+        let private = x25519_dalek::StaticSecret::random_from_rng(rand::rngs::OsRng);
+        let other_public = x25519_dalek::PublicKey::from(
+            &x25519_dalek::StaticSecret::random_from_rng(rand::rngs::OsRng),
+        );
+        let error = TomlConfigLoader::new_from_str(&format!(
+            r#"
+[secure_mode]
+enabled = true
+local_private_key = "{}"
+local_public_key = "{}"
+"#,
+            BASE64_STANDARD.encode(private.as_bytes()),
+            BASE64_STANDARD.encode(other_public.as_bytes())
+        ))
+        .unwrap_err();
+        let error = format!("{error:#}");
+
+        assert!(
+            error.contains("failed to normalize [secure_mode] config"),
+            "{error}"
+        );
+        assert!(
+            error.contains("does not match generated public key"),
+            "{error}"
+        );
+    }
+
+    #[test]
+    fn test_toml_secure_mode_disabled_keeps_keys_unset() {
+        let config = TomlConfigLoader::new_from_str(
+            r#"
+[secure_mode]
+enabled = false
+"#,
+        )
+        .unwrap();
+
+        let secure_mode = config.get_secure_mode().unwrap();
+        assert!(!secure_mode.enabled);
+        assert_eq!(secure_mode.local_private_key, None);
+        assert_eq!(secure_mode.local_public_key, None);
+    }
+
+    #[cfg(feature = "config-write")]
+    #[test]
+    fn test_toml_secure_mode_keypair_survives_roundtrip() {
+        let config = TomlConfigLoader::new_from_str(
+            r#"
+[secure_mode]
+enabled = true
+"#,
+        )
+        .unwrap();
+
+        let dumped = config.dump();
+        let restored = TomlConfigLoader::new_from_str(&dumped).unwrap();
+
+        assert_eq!(
+            config.get_secure_mode().unwrap(),
+            restored.get_secure_mode().unwrap()
+        );
+    }
+
     #[test]
     fn test_acl_toml_rule_uses_defaults_for_omitted_fields() {
         use crate::proto::acl::{Action, ChainType, Protocol};

easytier-core/src/connectivity/composite.rs

@@ -103,6 +103,17 @@ impl InterfaceAddrCache {
 /// Mechanical connector operations supplied by one process-wide runtime.
 #[async_trait]
 pub trait ConnectorRuntime: VirtualTcpSocketFactory + Send + Sync + 'static {
+    fn supports_external_tunnel(&self, _scheme: &str) -> bool {
+        false
+    }
+
+    async fn connect_external_tunnel(
+        &self,
+        _url: &Url,
+    ) -> anyhow::Result<Option<Box<dyn crate::tunnel::Tunnel>>> {
+        Ok(None)
+    }
+
     async fn connect_byte_stream(
         &self,
         url: &Url,
@@ -207,6 +218,17 @@ where
     S: ConnectorRuntime + VirtualUdpSocketFactory,
     E: ConnectorEnvironment,
 {
+    fn supports_external_tunnel(&self, scheme: &str) -> bool {
+        self.sockets.supports_external_tunnel(scheme)
+    }
+
+    async fn connect_external_tunnel(
+        &self,
+        url: &Url,
+    ) -> anyhow::Result<Option<Box<dyn crate::tunnel::Tunnel>>> {
+        self.sockets.connect_external_tunnel(url).await
+    }
+
     async fn local_addr_for_remote(
         &self,
         remote_addr: SocketAddr,

easytier-core/src/connectivity/connector_host.rs

@@ -24,6 +24,7 @@ use url::Url;
 use crate::{
     connectivity::{
         composite::{ConnectorEnvironment, ConnectorHostAdapter, ConnectorRuntime},
+        manual::ExternalTunnelConnector,
         transport::ConnectedByteStream,
     },
     host::environment::{HostConnectorEnvironmentIo, local_addr_for_remote},
@@ -113,6 +114,7 @@ where
     listeners: HostTcpListenerFactory<B>,
     environment: Arc<HostConnectorEnvironmentSnapshot>,
     environment_io: Arc<E>,
+    external_tunnel_connector: Option<Arc<dyn ExternalTunnelConnector>>,
 }
 
 impl<B, E> HostConnectorRuntime<B, E>
@@ -132,8 +134,17 @@ where
             listeners: HostTcpListenerFactory::new(runtime, backend),
             environment: Arc::new(environment),
             environment_io,
+            external_tunnel_connector: None,
         }
     }
+
+    pub fn with_external_tunnel_connector(
+        mut self,
+        connector: Arc<dyn ExternalTunnelConnector>,
+    ) -> Self {
+        self.external_tunnel_connector = Some(connector);
+        self
+    }
 }
 
 #[async_trait]
@@ -181,6 +192,25 @@ where
     B: ConnectorHostSocketBackend,
     E: HostConnectorEnvironmentIo,
 {
+    fn supports_external_tunnel(&self, scheme: &str) -> bool {
+        self.external_tunnel_connector
+            .as_ref()
+            .is_some_and(|connector| connector.supports_scheme(scheme))
+    }
+
+    async fn connect_external_tunnel(
+        &self,
+        url: &Url,
+    ) -> anyhow::Result<Option<Box<dyn crate::tunnel::Tunnel>>> {
+        let Some(connector) = &self.external_tunnel_connector else {
+            return Ok(None);
+        };
+        if !connector.supports_scheme(url.scheme()) {
+            return Ok(None);
+        }
+        Ok(Some(connector.connect(url).await?))
+    }
+
     async fn connect_byte_stream(
         &self,
         url: &Url,
@@ -257,6 +287,24 @@ where
     ConnectorHostAdapter::new(runtime.clone(), runtime)
 }
 
+pub fn new_connector_host_with_external_tunnel<B, E>(
+    socket_runtime: HostSocketRuntime,
+    backend: Arc<B>,
+    environment: HostConnectorEnvironmentSnapshot,
+    environment_io: Arc<E>,
+    connector: Arc<dyn ExternalTunnelConnector>,
+) -> ConnectorHost<B, E>
+where
+    B: ConnectorHostSocketBackend,
+    E: HostConnectorEnvironmentIo,
+{
+    let runtime = Arc::new(
+        HostConnectorRuntime::new(socket_runtime, backend, environment, environment_io)
+            .with_external_tunnel_connector(connector),
+    );
+    ConnectorHostAdapter::new(runtime.clone(), runtime)
+}
+
 #[cfg(test)]
 mod tests {
     use std::{
@@ -299,6 +347,19 @@ mod tests {
 
     struct FixedStunProvider;
 
+    struct ExternalFailingConnector;
+
+    #[async_trait]
+    impl ExternalTunnelConnector for ExternalFailingConnector {
+        fn supports_scheme(&self, scheme: &str) -> bool {
+            scheme == "ws"
+        }
+
+        async fn connect(&self, _url: &Url) -> anyhow::Result<Box<dyn crate::tunnel::Tunnel>> {
+            anyhow::bail!("external connector called")
+        }
+    }
+
     #[async_trait]
     impl StunInfoProvider for FixedStunProvider {
         fn get_stun_info(&self) -> StunInfo {
@@ -579,6 +640,34 @@ mod tests {
         );
     }
 
+    #[tokio::test]
+    async fn delegates_external_tunnel_connections() {
+        let host = new_connector_host_with_external_tunnel(
+            HostSocketRuntime::new(),
+            Arc::new(UnsupportedBackend::default()),
+            test_environment_snapshot(),
+            Arc::new(TestEnvironmentIo::default()),
+            Arc::new(ExternalFailingConnector),
+        );
+
+        let error = ManualConnectorHost::connect_external_tunnel(
+            &host,
+            &"ws://relay.example/".parse().unwrap(),
+        )
+        .await
+        .unwrap_err();
+        assert_eq!(error.to_string(), "external connector called");
+        assert!(
+            ManualConnectorHost::connect_external_tunnel(
+                &host,
+                &"tcp://relay.example:11010".parse().unwrap(),
+            )
+            .await
+            .unwrap()
+            .is_none()
+        );
+    }
+
     #[tokio::test]
     async fn direct_rpc_projects_host_observations_without_instance_policy() {
         let host = Arc::new(new_connector_host(

easytier-core/src/connectivity/direct/mod.rs

@@ -1,14 +1,12 @@
 use std::{
     collections::HashSet,
-    hash::Hash,
     net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr},
     sync::{Arc, Weak},
-    time::{Duration, Instant as StdInstant},
+    time::Duration,
 };
 
 use anyhow::Context;
 use async_trait::async_trait;
-use dashmap::DashMap;
 use quanta::Instant;
 use rand::Rng;
 use serde::{Deserialize, Serialize};
@@ -26,6 +24,7 @@ use crate::{
         },
         transport::{self, ConnectedTransport, UdpSessionMode},
     },
+    foundation::expiring_set::ExpiringSet,
     foundation::task::{PeerTaskLauncher, PeerTaskManager},
     host::dns::DnsResolver,
     peers::{
@@ -157,50 +156,6 @@ impl DirectConnectorOptions {
     }
 }
 
-#[derive(Debug)]
-struct ExpiringSet<K>
-where
-    K: Eq + Hash,
-{
-    entries: DashMap<K, StdInstant>,
-}
-
-impl<K> Default for ExpiringSet<K>
-where
-    K: Eq + Hash,
-{
-    fn default() -> Self {
-        Self {
-            entries: DashMap::new(),
-        }
-    }
-}
-
-impl<K> ExpiringSet<K>
-where
-    K: Eq + Hash + Clone,
-{
-    fn insert(&self, key: K, ttl: Duration) {
-        self.entries.insert(key, StdInstant::now() + ttl);
-    }
-
-    fn contains(&self, key: &K) -> bool {
-        let active = self
-            .entries
-            .get(key)
-            .is_some_and(|expires_at| *expires_at > StdInstant::now());
-        if !active {
-            self.entries.remove(key);
-        }
-        active
-    }
-
-    fn cleanup(&self) {
-        let now = StdInstant::now();
-        self.entries.retain(|_, expires_at| *expires_at > now);
-    }
-}
-
 #[derive(Debug, Hash, Eq, PartialEq, Clone)]
 struct ListenerBlacklistKey(PeerId, String);
 

easytier-core/src/connectivity/manual/mod.rs

@@ -94,6 +94,14 @@ pub struct ManualInterfaceAddrs {
 
 #[async_trait]
 pub trait ManualConnectorHost: VirtualTcpSocketFactory + VirtualUdpSocketFactory {
+    fn supports_external_tunnel(&self, _scheme: &str) -> bool {
+        false
+    }
+
+    async fn connect_external_tunnel(&self, _url: &Url) -> anyhow::Result<Option<Box<dyn Tunnel>>> {
+        Ok(None)
+    }
+
     async fn local_addr_for_remote(
         &self,
         remote_addr: SocketAddr,
@@ -110,6 +118,13 @@ pub trait ManualConnectorHost: VirtualTcpSocketFactory + VirtualUdpSocketFactory
     }
 }
 
+#[async_trait]
+pub trait ExternalTunnelConnector: Send + Sync + 'static {
+    fn supports_scheme(&self, scheme: &str) -> bool;
+
+    async fn connect(&self, url: &Url) -> anyhow::Result<Box<dyn Tunnel>>;
+}
+
 #[async_trait]
 pub(crate) trait ManualEndpointResolver: Send + Sync + 'static {
     async fn resolve_endpoint(&self, url: &Url) -> anyhow::Result<Url>;
@@ -182,6 +197,14 @@ where
             ));
         }
 
+        if let Some(tunnel) = self.host.connect_external_tunnel(&endpoint.url).await? {
+            return Ok(apply_resolved_endpoint_info(
+                tunnel,
+                requested_url,
+                endpoint.tunnel_prefixes,
+            ));
+        }
+
         if !self.protocol.supports_scheme(endpoint.url.scheme()) {
             anyhow::bail!(
                 "unsupported client protocol upgrader: {}",
@@ -710,17 +733,20 @@ where
             return Err(error);
         }
     };
-    let ip_versions = match resolve_reconnect_ip_versions(
-        &normalized_url,
-        connect_timeout,
-        ManualTransport::from_url(&normalized_url)
-            .ok()
-            .map(|transport| data.options.socket_context(transport, IpVersion::Both))
-            .unwrap_or_default(),
-        data.dns.as_ref(),
-    )
-    .await
-    {
+    let ip_versions = match if data.host.supports_external_tunnel(normalized_url.scheme()) {
+        Ok(vec![IpVersion::Both])
+    } else {
+        resolve_reconnect_ip_versions(
+            &normalized_url,
+            connect_timeout,
+            ManualTransport::from_url(&normalized_url)
+                .ok()
+                .map(|transport| data.options.socket_context(transport, IpVersion::Both))
+                .unwrap_or_default(),
+            data.dns.as_ref(),
+        )
+        .await
+    } {
         Ok(ip_versions) => ip_versions,
         Err(error) => {
             emit_connect_error(&data, &url, IpVersion::Both, &error);
@@ -770,13 +796,17 @@ where
         ),
     )
     .await?;
-    if endpoint.url.scheme() != "ring" && !data.protocol.supports_scheme(endpoint.url.scheme()) {
+    let uses_external_tunnel = data.host.supports_external_tunnel(endpoint.url.scheme());
+    if endpoint.url.scheme() != "ring"
+        && !uses_external_tunnel
+        && !data.protocol.supports_scheme(endpoint.url.scheme())
+    {
         anyhow::bail!(
             "unsupported client protocol upgrader: {}",
             endpoint.url.scheme()
         );
     }
-    let transport = (endpoint.url.scheme() != "ring")
+    let transport = (endpoint.url.scheme() != "ring" && !uses_external_tunnel)
         .then(|| ManualTransport::from_url(&endpoint.url))
         .transpose()?;
     let resolved = match transport {
@@ -822,6 +852,15 @@ where
         if endpoint.url.scheme() == "ring" {
             return connect_ring_tunnel(&data.ring_registry, &endpoint.url);
         }
+        if uses_external_tunnel {
+            return data
+                .host
+                .connect_external_tunnel(&endpoint.url)
+                .await?
+                .ok_or_else(|| {
+                    anyhow::anyhow!("host did not provide external tunnel for {}", endpoint.url)
+                });
+        }
         let transport = transport.expect("non-Ring endpoint should have a transport");
         let connected = match resolved {
             Some((remote_addr, bind_addrs)) => {

easytier-core/src/foundation/expiring_set.rs

@@ -0,0 +1,71 @@
+use std::{hash::Hash, time::Duration, time::Instant};
+
+use dashmap::DashMap;
+
+/// A thread-safe set whose entries expire after a per-insert TTL.
+///
+/// `contains` lazily removes expired entries, so periodic `cleanup` calls
+/// are only needed to reclaim memory for keys that stop being read.
+#[derive(Debug, Clone)]
+pub struct ExpiringSet<K>
+where
+    K: Eq + Hash,
+{
+    entries: DashMap<K, Instant>,
+}
+
+impl<K> Default for ExpiringSet<K>
+where
+    K: Eq + Hash,
+{
+    fn default() -> Self {
+        Self {
+            entries: DashMap::new(),
+        }
+    }
+}
+
+impl<K> ExpiringSet<K>
+where
+    K: Eq + Hash + Clone,
+{
+    pub fn insert(&self, key: K, ttl: Duration) {
+        self.entries.insert(key, Instant::now() + ttl);
+    }
+
+    pub fn contains(&self, key: &K) -> bool {
+        match self
+            .entries
+            .remove_if(key, |_, expires_at| *expires_at <= Instant::now())
+        {
+            // Existed and expired: removed while holding the shard lock, so a
+            // concurrent insert of the same key cannot be dropped by us.
+            Some(_) => false,
+            // Not removed: either absent, or still fresh.
+            None => self.entries.contains_key(key),
+        }
+    }
+
+    pub fn cleanup(&self) {
+        let now = Instant::now();
+        self.entries.retain(|_, expires_at| *expires_at > now);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::time::Duration;
+
+    use super::*;
+
+    #[test]
+    fn expired_entries_are_reported_absent() {
+        let set: ExpiringSet<u32> = ExpiringSet::default();
+        set.insert(1, Duration::ZERO);
+        set.insert(2, Duration::from_secs(3600));
+        assert!(!set.contains(&1));
+        assert!(set.contains(&2));
+        set.cleanup();
+        assert!(!set.entries.contains_key(&1));
+    }
+}

easytier-core/src/foundation/mod.rs

@@ -3,6 +3,7 @@
 //! Everything in `foundation` may be used by any layer, and nothing here may
 //! depend on a domain Module. See `CONTEXT.md` "Module layers".
 
+pub mod expiring_set;
 #[cfg(any(
     feature = "proxy-smoltcp-stack",
     test,

easytier-core/src/foundation/token_bucket.rs

@@ -10,17 +10,11 @@ use tokio_util::task::AbortOnDropHandle;
 
 use crate::foundation::time;
 
-#[async_trait::async_trait]
 pub(crate) trait ByteLimiter: Send + Sync {
-    async fn consume(&self, bytes: u64);
-
     fn try_consume(&self, bytes: u64) -> bool;
 }
 
-#[async_trait::async_trait]
 impl ByteLimiter for () {
-    async fn consume(&self, _bytes: u64) {}
-
     fn try_consume(&self, _bytes: u64) -> bool {
         true
     }
@@ -123,16 +117,19 @@ impl TokenBucket {
 
     /// Attempt to consume tokens without blocking
     ///
+    /// Requests larger than the bucket capacity are charged one full
+    /// bucket instead of being rejected, so oversized packets can still
+    /// pass whenever the bucket holds a full burst; traffic consisting
+    /// only of oversized packets can therefore sustain up to
+    /// packet-size/capacity times the nominal rate.
+    ///
     /// # Returns
     /// `true` if tokens were consumed, `false` if insufficient tokens
     pub fn try_consume(&self, tokens: u64) -> bool {
         if self.stopped.load(Ordering::Acquire) {
             return true;
         }
-        // Fast path for oversized packets
-        if tokens > self.config.capacity {
-            return false;
-        }
+        let tokens = tokens.min(self.config.capacity);
 
         let mut state = self.state.lock();
         self.refill(&mut state, Instant::now());
@@ -194,12 +191,7 @@ impl TokenBucket {
     }
 }
 
-#[async_trait::async_trait]
 impl ByteLimiter for TokenBucket {
-    async fn consume(&self, bytes: u64) {
-        TokenBucket::consume(self, bytes).await;
-    }
-
     fn try_consume(&self, bytes: u64) -> bool {
         TokenBucket::try_consume(self, bytes)
     }
@@ -469,13 +461,19 @@ mod tests {
     /// Test behavior when packet size exceeds capacity
     #[tokio::test]
     async fn test_oversized_packet() {
-        let bucket = TokenBucket::new(1500, 1000);
+        // Fill rate of 1 token/s keeps the test independent of timing:
+        // even a long scheduling stall cannot refill a meaningful amount.
+        let bucket = TokenBucket::new(1500, 1);
 
-        // Packet larger than capacity should be rejected
-        assert!(!bucket.try_consume(1600));
+        // Oversized packets are charged one full bucket instead of
+        // being rejected, so a full bucket always admits them.
+        assert!(bucket.try_consume(1600));
+        assert_eq!(bucket.state.lock().available_tokens, 0);
 
-        // Regular packets should still work
+        // A partially drained bucket still rejects them.
+        let bucket = TokenBucket::new(1500, 1);
         assert!(bucket.try_consume(1000));
+        assert!(!bucket.try_consume(1600));
     }
 
     #[tokio::test]

easytier-core/src/gateway/dataplane/mod.rs

@@ -590,8 +590,6 @@ where
         })?;
         let overlay_destination = if local_virtual_destination {
             true
-        } else if dst_ip.is_loopback() {
-            false
         } else {
             let (peers, _) = options
                 .deadline

easytier-core/src/gateway/dataplane/operation.rs

@@ -53,6 +53,7 @@ pub enum DataPlaneOperationKind {
     UdpBind = 6,
     UdpReceive = 7,
     UdpSend = 8,
+    TcpShutdownWrite = 9,
 }
 
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
@@ -100,6 +101,7 @@ pub enum DataPlaneOperationResult {
     TcpWritten {
         len: usize,
     },
+    TcpWriteShutdown,
     UdpBound {
         socket: DataPlaneResourceId,
         local_addr: SocketAddr,
@@ -136,6 +138,7 @@ impl DataPlaneOperationResult {
             Self::UdpBound { socket, .. } => Some(*socket),
             Self::TcpRead { .. }
             | Self::TcpWritten { .. }
+            | Self::TcpWriteShutdown
             | Self::UdpReceived { .. }
             | Self::UdpSent { .. } => None,
         }

easytier-core/src/gateway/dataplane/session.rs

@@ -168,6 +168,7 @@ enum PendingOperationResult {
         eof: bool,
     },
     TcpWritten(usize),
+    TcpWriteShutdown,
     UdpBound(DataPlaneUdpSocket),
     UdpReceived {
         data: Vec<u8>,
@@ -624,6 +625,36 @@ where
         Ok(operation_id)
     }
 
+    pub fn submit_tcp_shutdown_write(
+        self: &Arc<Self>,
+        stream_id: DataPlaneResourceId,
+    ) -> DataPlaneResult<DataPlaneOperationId> {
+        Self::ensure_executor()?;
+        let (stream, operation_id, cancel) = {
+            let mut state = self.lock_state();
+            let stream = Self::require_tcp(&state, stream_id)?;
+            let (operation_id, cancel) = self.admit_locked(
+                &mut state,
+                DataPlaneOperationKind::TcpShutdownWrite,
+                Some(stream_id),
+                0,
+                false,
+            )?;
+            (stream, operation_id, cancel)
+        };
+        self.spawn_operation(operation_id, async move {
+            stream
+                .write_deadline
+                .run(cancel, async {
+                    stream.write.lock().await.shutdown().await?;
+                    Ok::<_, std::io::Error>(())
+                })
+                .await?;
+            Ok(PendingOperationResult::TcpWriteShutdown)
+        });
+        Ok(operation_id)
+    }
+
     pub fn submit_udp_bind(
         self: &Arc<Self>,
         local_port: u16,
@@ -880,6 +911,7 @@ where
                 DataPlaneOperationResult::TcpRead { data, eof }
             }
             PendingOperationResult::TcpWritten(len) => DataPlaneOperationResult::TcpWritten { len },
+            PendingOperationResult::TcpWriteShutdown => DataPlaneOperationResult::TcpWriteShutdown,
             PendingOperationResult::UdpBound(socket) => {
                 let local_addr = socket.local_addr();
                 let socket = Self::insert_udp_resource_locked(resources, socket)?;

easytier-core/src/gateway/dataplane/tests.rs

@@ -327,6 +327,55 @@ async fn data_plane_sessions_complete_tcp_operations_end_to_end() {
     assert_eq!(written, 4);
     assert_eq!(received, b"ping");
 
+    let eof_read = session_b.submit_tcp_read(server, 16).unwrap();
+    let shutdown = session_a.submit_tcp_shutdown_write(client).unwrap();
+    let shutdown_completion = wait_for_session_completion(&session_a).await;
+    let eof_completion = wait_for_session_completion(&session_b).await;
+    assert_eq!(shutdown_completion.operation_id, shutdown);
+    assert_eq!(eof_completion.operation_id, eof_read);
+    session_a
+        .take_result_with(shutdown, |outcome| match outcome {
+            Ok(DataPlaneOperationResult::TcpWriteShutdown) => Some(()),
+            _ => None,
+        })
+        .unwrap()
+        .unwrap();
+    let eof = session_b
+        .take_result_with(eof_read, |outcome| match outcome {
+            Ok(DataPlaneOperationResult::TcpRead { data, eof }) => Some((data.clone(), *eof)),
+            _ => None,
+        })
+        .unwrap()
+        .unwrap();
+    assert_eq!(eof, (Vec::new(), true));
+
+    let response_read = session_a.submit_tcp_read(client, 16).unwrap();
+    let response_write = session_b
+        .submit_tcp_write(server, b"pong".to_vec())
+        .unwrap();
+    let (response_read_completion, response_write_completion) = tokio::join!(
+        wait_for_session_completion(&session_a),
+        wait_for_session_completion(&session_b),
+    );
+    assert_eq!(response_read_completion.operation_id, response_read);
+    assert_eq!(response_write_completion.operation_id, response_write);
+    let response = session_a
+        .take_result_with(response_read, |outcome| match outcome {
+            Ok(DataPlaneOperationResult::TcpRead { data, eof }) if !eof => Some(data.clone()),
+            _ => None,
+        })
+        .unwrap()
+        .unwrap();
+    let response_len = session_b
+        .take_result_with(response_write, |outcome| match outcome {
+            Ok(DataPlaneOperationResult::TcpWritten { len }) => Some(*len),
+            _ => None,
+        })
+        .unwrap()
+        .unwrap();
+    assert_eq!(response, b"pong");
+    assert_eq!(response_len, 4);
+
     let blocked_read = session_b.submit_tcp_read(server, 16).unwrap();
     session_b.close_resource(server);
     let close_completion = wait_for_session_completion(&session_b).await;

easytier-core/src/gateway/dhcp.rs

@@ -1,4 +1,4 @@
-use std::{collections::HashSet, net::Ipv4Addr, sync::Arc, time::Duration};
+use std::{collections::HashSet, sync::Arc, time::Duration};
 
 use async_trait::async_trait;
 use cidr::Ipv4Inet;
@@ -22,22 +22,16 @@ pub enum DhcpIpv4Decision {
     },
 }
 
-#[derive(Debug)]
+#[derive(Debug, Default)]
 pub struct DhcpIpv4Allocator {
-    default_subnet: Ipv4Inet,
+    default_subnet: Option<Ipv4Inet>,
     current: Option<Ipv4Inet>,
 }
 
-impl Default for DhcpIpv4Allocator {
-    fn default() -> Self {
-        Self::new(Ipv4Inet::new(Ipv4Addr::new(10, 126, 126, 0), 24).unwrap())
-    }
-}
-
 impl DhcpIpv4Allocator {
     pub fn new(default_subnet: Ipv4Inet) -> Self {
         Self {
-            default_subnet,
+            default_subnet: Some(default_subnet),
             current: None,
         }
     }
@@ -59,7 +53,13 @@ impl DhcpIpv4Allocator {
             return DhcpIpv4Decision::WaitForPeers;
         }
 
-        let subnet = used_ipv4.iter().next().unwrap_or(&self.default_subnet);
+        let Some(subnet) = self
+            .default_subnet
+            .as_ref()
+            .or_else(|| used_ipv4.iter().next())
+        else {
+            return DhcpIpv4Decision::WaitForPeers;
+        };
         if let Some(current) = self.current
             && current.network() == subnet.network()
             && !used_ipv4.contains(&current)
@@ -410,15 +410,12 @@ mod tests {
     }
 
     #[test]
-    fn uses_default_subnet_when_routes_have_no_ipv4() {
+    fn does_not_fall_back_to_a_builtin_subnet_without_assigned_ipv4() {
         let allocator = DhcpIpv4Allocator::default();
 
         assert_eq!(
             allocator.evaluate(true, &HashSet::new()),
-            DhcpIpv4Decision::Change {
-                previous: None,
-                next: Some("10.126.126.1/24".parse().unwrap()),
-            }
+            DhcpIpv4Decision::WaitForPeers
         );
     }
 
@@ -460,7 +457,7 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn service_commits_only_after_host_apply_succeeds() {
+    async fn service_does_not_apply_ipv4_when_no_peer_has_one() {
         let host = Arc::new(RecordingHost::default());
         let (service, runtime_config) = service(
             DhcpIpv4RouteSnapshot {
@@ -472,21 +469,49 @@ mod tests {
 
         assert!(service.reconcile_once().await);
 
-        assert_eq!(service.current(), Some("10.126.126.1/24".parse().unwrap()));
+        assert_eq!(service.current(), None);
+        assert!(host.changes.lock().unwrap().is_empty());
+        assert!(host.published.lock().unwrap().is_empty());
+        assert!(
+            runtime_config
+                .snapshot()
+                .peer
+                .runtime
+                .core
+                .routes
+                .ipv4
+                .is_none()
+        );
+    }
+
+    #[tokio::test]
+    async fn service_commits_only_after_host_apply_succeeds() {
+        let host = Arc::new(RecordingHost::default());
+        let (service, runtime_config) = service(
+            DhcpIpv4RouteSnapshot {
+                has_routes: true,
+                used_ipv4: HashSet::from(["198.18.0.2/24".parse().unwrap()]),
+            },
+            host.clone(),
+        );
+
+        assert!(service.reconcile_once().await);
+
+        assert_eq!(service.current(), Some("198.18.0.1/24".parse().unwrap()));
         assert_eq!(
             *host.changes.lock().unwrap(),
-            [(None, Some("10.126.126.1/24".parse().unwrap()))]
+            [(None, Some("198.18.0.1/24".parse().unwrap()))]
         );
         assert_eq!(
             runtime_config.snapshot().peer.runtime.core.routes.ipv4,
-            Some(IpPrefix::new("10.126.126.1".parse().unwrap(), 24).unwrap())
+            Some(IpPrefix::new("198.18.0.1".parse().unwrap(), 24).unwrap())
         );
         assert_eq!(
             *host.published.lock().unwrap(),
             [(
                 None,
-                Some("10.126.126.1/24".parse().unwrap()),
-                Some("10.126.126.1/24".parse().unwrap())
+                Some("198.18.0.1/24".parse().unwrap()),
+                Some("198.18.0.1/24".parse().unwrap())
             )]
         );
     }
@@ -498,14 +523,14 @@ mod tests {
         let (service, _runtime_config) = service(
             DhcpIpv4RouteSnapshot {
                 has_routes: true,
-                used_ipv4: HashSet::new(),
+                used_ipv4: HashSet::from(["198.18.0.2/24".parse().unwrap()]),
             },
             host.clone(),
         );
 
         service.reconcile_once().await;
 
-        let expected = Some(IpPrefix::new("10.126.126.1".parse().unwrap(), 24).unwrap());
+        let expected = Some(IpPrefix::new("198.18.0.1".parse().unwrap(), 24).unwrap());
         assert!(host.published_with_permit.load(Ordering::Acquire));
         assert_eq!(
             host.published_runtime_ipv4.lock().unwrap().as_slice(),
@@ -521,7 +546,7 @@ mod tests {
         let (service, runtime_config) = service(
             DhcpIpv4RouteSnapshot {
                 has_routes: true,
-                used_ipv4: HashSet::new(),
+                used_ipv4: HashSet::from(["198.18.0.2/24".parse().unwrap()]),
             },
             host.clone(),
         );
@@ -544,7 +569,7 @@ mod tests {
         let (service, _runtime_config) = service(
             DhcpIpv4RouteSnapshot {
                 has_routes: true,
-                used_ipv4: HashSet::new(),
+                used_ipv4: HashSet::from(["198.18.0.2/24".parse().unwrap()]),
             },
             host.clone(),
         );
@@ -556,8 +581,8 @@ mod tests {
         assert_eq!(
             host.changes.lock().unwrap().as_slice(),
             [
-                (None, Some("10.126.126.1/24".parse().unwrap())),
-                (None, Some("10.126.126.1/24".parse().unwrap())),
+                (None, Some("198.18.0.1/24".parse().unwrap())),
+                (None, Some("198.18.0.1/24".parse().unwrap())),
             ]
         );
     }

easytier-core/src/gateway/port_forward.rs

@@ -256,17 +256,6 @@ where
             Arc::downgrade(&connections),
             "TCP port-forward connections",
         ));
-        if self.runtime_config.snapshot().services.proxy.force_smoltcp
-            && bind_addr.is_ipv4()
-            && bind_addr.ip().is_unspecified()
-        {
-            self.spawn_data_plane_tcp_port_forward(
-                bind_addr.port(),
-                dst_addr,
-                cancel.clone(),
-                connections.clone(),
-            );
-        }
         let host = self.host.clone();
         self.tasks.lock().unwrap().spawn(async move {
             let mut listener = Some(listener);
@@ -314,98 +303,6 @@ where
         Ok(())
     }
 
-    fn spawn_data_plane_tcp_port_forward(
-        &self,
-        local_port: u16,
-        dst_addr: SocketAddr,
-        cancel: CancellationToken,
-        connections: Arc<std::sync::Mutex<JoinSet<()>>>,
-    ) {
-        let data_plane = self.data_plane.clone();
-        self.tasks.lock().unwrap().spawn(async move {
-            loop {
-                let mut listener = match select! {
-                    biased;
-                    _ = cancel.cancelled() => break,
-                    result = data_plane.data_plane_tcp_bind(local_port, Duration::from_secs(10)) => result,
-                } {
-                    Ok(listener) => listener,
-                    Err(error) => {
-                        tracing::error!(
-                            ?error,
-                            local_port,
-                            "data-plane TCP port-forward bind failed"
-                        );
-                        select! {
-                            biased;
-                            _ = cancel.cancelled() => break,
-                            _ = crate::foundation::time::sleep(TCP_PORT_FORWARD_REBIND_DELAY) => continue,
-                        }
-                    }
-                };
-                tracing::info!(
-                    ?dst_addr,
-                    local_addr = ?listener.local_addr(),
-                    "data-plane TCP port-forward listener bound"
-                );
-
-                loop {
-                    let accepted = select! {
-                        biased;
-                        _ = cancel.cancelled() => return,
-                        result = listener.accept() => result,
-                    };
-                    let (mut incoming, source_addr) = match accepted {
-                        Ok(accepted) => accepted,
-                        Err(error) => {
-                            tracing::error!(
-                                ?error,
-                                local_port,
-                                "data-plane TCP port-forward accept failed; rebinding"
-                            );
-                            break;
-                        }
-                    };
-                    let data_plane = data_plane.clone();
-                    connections.lock().unwrap().spawn(async move {
-                        let options = DataPlaneTcpConnectOptions::gateway(
-                            Duration::from_secs(10),
-                            TcpSocketPurpose::PortForward,
-                            source_addr,
-                        );
-                        let mut outgoing = match data_plane.connect_tcp(dst_addr, options).await {
-                            Ok(stream) => stream,
-                            Err(error) => {
-                                tracing::error!(?error, ?dst_addr, "port-forward connect failed");
-                                return;
-                            }
-                        };
-                        match tokio::io::copy_bidirectional(&mut incoming, &mut outgoing).await {
-                            Ok((from_client, from_server)) => tracing::info!(
-                                ?dst_addr,
-                                from_client,
-                                from_server,
-                                "port-forward connection finished"
-                            ),
-                            Err(error) => tracing::error!(
-                                ?error,
-                                ?dst_addr,
-                                "port-forward connection failed"
-                            ),
-                        }
-                    });
-                }
-
-                drop(listener);
-                select! {
-                    biased;
-                    _ = cancel.cancelled() => break,
-                    _ = crate::foundation::time::sleep(TCP_PORT_FORWARD_REBIND_DELAY) => {}
-                }
-            }
-        });
-    }
-
     async fn add_udp_port_forward(&self, cfg: &PortForwardConfig) -> anyhow::Result<()> {
         let (bind_addr, dst_addr) = (cfg.bind_addr, cfg.dst_addr);
         let forward = cfg.clone();

easytier-core/src/gateway/proxy/tcp_proxy_engine.rs

@@ -9,7 +9,7 @@ use std::{
 
 use cidr::Ipv4Inet;
 use crossbeam::atomic::AtomicCell;
-use dashmap::DashMap;
+use dashmap::{DashMap, mapref::entry::Entry};
 use smoltcp::wire::{IpAddress, IpProtocol, Ipv4Packet, TcpPacket};
 
 use crate::packet::{PacketType, ZCPacket};
@@ -25,6 +25,16 @@ pub(crate) enum TcpProxyMode {
     QuicSrc,
 }
 
+impl TcpProxyMode {
+    pub(super) const fn smoltcp_listener_port(self) -> u16 {
+        match self {
+            Self::Tcp => 8899,
+            Self::KcpSrc => 8900,
+            Self::QuicSrc => 8901,
+        }
+    }
+}
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum TcpNatEntryState {
     SynReceived,
@@ -44,24 +54,30 @@ pub struct TcpNatEntrySnapshot {
     pub state: TcpNatEntryState,
 }
 
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+struct TcpNatFlowKey {
+    src: SocketAddr,
+    mapped_dst: SocketAddr,
+}
+
 #[derive(Debug)]
 pub(crate) struct TcpNatEntry {
     id: TcpNatEntryId,
-    src: SocketAddr,
+    flow: TcpNatFlowKey,
+    translated_src: SocketAddr,
     real_dst: SocketAddr,
-    mapped_dst: SocketAddr,
     start_time: Instant,
     start_time_unix_secs: u64,
     state: AtomicCell<TcpNatEntryState>,
 }
 
 impl TcpNatEntry {
-    fn new(src: SocketAddr, real_dst: SocketAddr, mapped_dst: SocketAddr) -> Self {
+    fn new(flow: TcpNatFlowKey, translated_src: SocketAddr, real_dst: SocketAddr) -> Self {
         Self {
             id: uuid::Uuid::new_v4(),
-            src,
+            flow,
+            translated_src,
             real_dst,
-            mapped_dst,
             start_time: Instant::now(),
             start_time_unix_secs: SystemTime::now()
                 .duration_since(UNIX_EPOCH)
@@ -76,7 +92,7 @@ impl TcpNatEntry {
     }
 
     pub fn src(&self) -> SocketAddr {
-        self.src
+        self.flow.src
     }
 
     pub fn real_dst(&self) -> SocketAddr {
@@ -84,7 +100,7 @@ impl TcpNatEntry {
     }
 
     pub fn mapped_dst(&self) -> SocketAddr {
-        self.mapped_dst
+        self.flow.mapped_dst
     }
 
     pub fn state(&self) -> TcpNatEntryState {
@@ -97,9 +113,9 @@ impl TcpNatEntry {
 
     fn snapshot(&self) -> TcpNatEntrySnapshot {
         TcpNatEntrySnapshot {
-            src: self.src,
+            src: self.src(),
             dst: self.real_dst,
-            mapped_dst: self.mapped_dst,
+            mapped_dst: self.mapped_dst(),
             start_time: self.start_time_unix_secs,
             state: self.state(),
         }
@@ -127,6 +143,7 @@ pub(crate) struct TcpProxyNicContext {
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(crate) enum TcpProxyPacketAction {
     Handled { new_syn: bool },
+    Drop,
     Pass,
 }
 
@@ -134,9 +151,10 @@ pub(crate) enum TcpProxyPacketAction {
 pub(crate) struct TcpProxyEngine {
     cidr_table: Arc<ProxyCidrTable>,
     local_port: AtomicU16,
-    syn_map: DashMap<SocketAddr, Arc<TcpNatEntry>>,
+    next_translated_port: AtomicU16,
+    flow_map: DashMap<TcpNatFlowKey, Arc<TcpNatEntry>>,
+    translated_src_map: DashMap<SocketAddr, Arc<TcpNatEntry>>,
     conn_map: DashMap<uuid::Uuid, Arc<TcpNatEntry>>,
-    addr_conn_map: DashMap<SocketAddr, Arc<TcpNatEntry>>,
 }
 
 impl TcpProxyEngine {
@@ -144,9 +162,10 @@ impl TcpProxyEngine {
         Self {
             cidr_table,
             local_port: AtomicU16::new(0),
-            syn_map: DashMap::new(),
+            next_translated_port: AtomicU16::new(1),
+            flow_map: DashMap::new(),
+            translated_src_map: DashMap::new(),
             conn_map: DashMap::new(),
-            addr_conn_map: DashMap::new(),
         }
     }
 
@@ -158,6 +177,61 @@ impl TcpProxyEngine {
         self.local_port.load(Ordering::Relaxed)
     }
 
+    fn allocate_entry(
+        &self,
+        flow: TcpNatFlowKey,
+        real_dst: SocketAddr,
+    ) -> Option<Arc<TcpNatEntry>> {
+        let local_port = self.local_port();
+        for _ in 0..u16::MAX {
+            let translated_port = self
+                .next_translated_port
+                .fetch_update(Ordering::Relaxed, Ordering::Relaxed, |port| {
+                    Some(if port == u16::MAX { 1 } else { port + 1 })
+                })
+                .expect("translated port counter update cannot fail");
+            if translated_port == local_port {
+                continue;
+            }
+            let translated_src = SocketAddr::new(flow.src.ip(), translated_port);
+            let Entry::Vacant(slot) = self.translated_src_map.entry(translated_src) else {
+                continue;
+            };
+            let entry = Arc::new(TcpNatEntry::new(flow, translated_src, real_dst));
+            slot.insert(entry.clone());
+            return Some(entry);
+        }
+        None
+    }
+
+    fn entry_for_syn(
+        &self,
+        flow: TcpNatFlowKey,
+        real_dst: SocketAddr,
+    ) -> Option<(Arc<TcpNatEntry>, bool)> {
+        match self.flow_map.entry(flow) {
+            Entry::Occupied(mut slot) => {
+                let entry = slot.get();
+                if !matches!(
+                    entry.state(),
+                    TcpNatEntryState::ClosingSrc
+                        | TcpNatEntryState::ClosingDst
+                        | TcpNatEntryState::Closed
+                ) {
+                    return Some((entry.clone(), false));
+                }
+                let entry = self.allocate_entry(flow, real_dst)?;
+                slot.insert(entry.clone());
+                Some((entry, true))
+            }
+            Entry::Vacant(slot) => {
+                let entry = self.allocate_entry(flow, real_dst)?;
+                slot.insert(entry.clone());
+                Some((entry, true))
+            }
+        }
+    }
+
     pub fn check_packet_from_peer_fast(
         &self,
         mode: TcpProxyMode,
@@ -230,28 +304,36 @@ impl TcpProxyEngine {
 
         let source_ip = ip_packet.src_addr();
         let source_port = tcp_packet.src_port();
-        let src = SocketAddr::V4(SocketAddrV4::new(source_ip, source_port));
+        let dest_ip = ip_packet.dst_addr();
+        let dest_port = tcp_packet.dst_port();
+        let flow = TcpNatFlowKey {
+            src: SocketAddr::V4(SocketAddrV4::new(source_ip, source_port)),
+            mapped_dst: SocketAddr::V4(SocketAddrV4::new(dest_ip, dest_port)),
+        };
 
-        let mut new_syn = false;
-        if tcp_packet.syn() && !tcp_packet.ack() {
-            let dest_ip = ip_packet.dst_addr();
-            let dest_port = tcp_packet.dst_port();
-            let mapped_dst = SocketAddr::V4(SocketAddrV4::new(dest_ip, dest_port));
+        let is_syn = tcp_packet.syn() && !tcp_packet.ack();
+        let (entry, new_syn) = if is_syn {
             let real_dst = SocketAddr::V4(SocketAddrV4::new(real_dst_ip, dest_port));
+            let Some(entry) = self.entry_for_syn(flow, real_dst) else {
+                tracing::error!(?flow, "tcp proxy translated source ports exhausted");
+                return TcpProxyPacketAction::Drop;
+            };
+            entry
+        } else {
+            let Some(entry) = self.flow_map.get(&flow) else {
+                return TcpProxyPacketAction::Pass;
+            };
+            (entry.clone(), false)
+        };
 
-            let old_val = self
-                .syn_map
-                .insert(src, Arc::new(TcpNatEntry::new(src, real_dst, mapped_dst)));
+        if new_syn {
             tracing::info!(
-                ?src,
-                ?real_dst,
-                ?mapped_dst,
-                old_entry = ?old_val,
+                src = ?entry.src(),
+                translated_src = ?entry.translated_src,
+                real_dst = ?entry.real_dst(),
+                mapped_dst = ?entry.mapped_dst(),
                 "tcp syn received"
             );
-            new_syn = true;
-        } else if !self.addr_conn_map.contains_key(&src) && !self.syn_map.contains_key(&src) {
-            return TcpProxyPacketAction::Pass;
         }
 
         let mut ip_packet = Ipv4Packet::new_checked(payload_bytes).expect("checked ipv4 packet");
@@ -263,6 +345,7 @@ impl TcpProxyEngine {
         {
             let mut tcp_packet =
                 TcpPacket::new_checked(ip_packet.payload_mut()).expect("checked tcp packet");
+            tcp_packet.set_src_port(entry.translated_src.port());
             tcp_packet.set_dst_port(ctx.local_port);
             tcp_packet.fill_checksum(&IpAddress::Ipv4(source), &IpAddress::Ipv4(local_ip));
         }
@@ -312,17 +395,13 @@ impl TcpProxyEngine {
         }
 
         tracing::trace!(?dst_addr, "tcp packet try find entry");
-        let entry = if let Some(entry) = self.addr_conn_map.get(&dst_addr) {
-            entry.clone()
-        } else {
-            let Some(syn_entry) = self.syn_map.get(&dst_addr) else {
-                return false;
-            };
-            syn_entry.clone()
+        let Some(entry) = self.translated_src_map.get(&dst_addr) else {
+            return false;
         };
-        assert_eq!(entry.src, dst_addr);
+        let entry = entry.clone();
+        assert_eq!(entry.translated_src, dst_addr);
 
-        let IpAddr::V4(mapped_dst_ip) = entry.mapped_dst.ip() else {
+        let IpAddr::V4(mapped_dst_ip) = entry.mapped_dst().ip() else {
             panic!("v4 nat entry src ip is not v4");
         };
 
@@ -346,6 +425,7 @@ impl TcpProxyEngine {
             let mut tcp_packet =
                 TcpPacket::new_checked(ip_packet.payload_mut()).expect("checked tcp packet");
             tcp_packet.set_src_port(entry.real_dst.port());
+            tcp_packet.set_dst_port(entry.src().port());
             tcp_packet.fill_checksum(&IpAddress::Ipv4(mapped_dst_ip), &IpAddress::Ipv4(dst));
         }
         ip_packet.fill_checksum();
@@ -366,53 +446,90 @@ impl TcpProxyEngine {
             }
         }
 
-        let (_, entry) = self.syn_map.remove(&socket_addr)?;
-        if entry.state() != TcpNatEntryState::SynReceived {
+        let entry = self.translated_src_map.get(&socket_addr)?.clone();
+        if entry
+            .state
+            .compare_exchange(
+                TcpNatEntryState::SynReceived,
+                TcpNatEntryState::ConnectingDst,
+            )
+            .is_err()
+        {
+            if entry.state() == TcpNatEntryState::Closed {
+                self.remove_indices(&entry);
+            }
             return None;
         }
 
-        entry.set_state(TcpNatEntryState::ConnectingDst);
-        self.addr_conn_map.insert(entry.src, entry.clone());
         let old_nat_val = self.conn_map.insert(entry.id, entry.clone());
         assert!(old_nat_val.is_none());
         Some(entry)
     }
 
+    fn remove_indices(&self, entry: &TcpNatEntry) {
+        self.flow_map
+            .remove_if(&entry.flow, |_, current| current.id == entry.id);
+        self.translated_src_map
+            .remove_if(&entry.translated_src, |_, current| current.id == entry.id);
+    }
+
     pub fn remove_entry(&self, entry_id: TcpNatEntryId) {
         let Some((_, entry)) = self.conn_map.remove(&entry_id) else {
             return;
         };
-        self.addr_conn_map
-            .remove_if(&entry.src, |_, current| current.id == entry.id);
+        self.remove_indices(&entry);
         if self.conn_map.capacity() - self.conn_map.len() > 16 {
             self.conn_map.shrink_to_fit();
         }
-        if self.addr_conn_map.capacity() - self.addr_conn_map.len() > 16 {
-            self.addr_conn_map.shrink_to_fit();
+        if self.flow_map.capacity() - self.flow_map.len() > 16 {
+            self.flow_map.shrink_to_fit();
+        }
+        if self.translated_src_map.capacity() - self.translated_src_map.len() > 16 {
+            self.translated_src_map.shrink_to_fit();
         }
     }
 
-    pub fn cleanup_expired_syn(&self, timeout: Duration) {
-        self.syn_map.retain(|_, entry| {
-            if entry.start_time.elapsed() > timeout {
-                tracing::warn!(?entry, "syn nat entry expired");
-                entry.set_state(TcpNatEntryState::Closed);
-                false
-            } else {
-                true
-            }
-        });
-        self.syn_map.shrink_to_fit();
+    pub fn clear(&self) {
+        for entry in self.flow_map.iter() {
+            entry.set_state(TcpNatEntryState::Closed);
+        }
+        for entry in self.conn_map.iter() {
+            entry.set_state(TcpNatEntryState::Closed);
+        }
+        self.flow_map.clear();
+        self.translated_src_map.clear();
+        self.conn_map.clear();
     }
 
-    pub fn is_tcp_proxy_connection(&self, src: SocketAddr) -> bool {
-        self.syn_map.contains_key(&src) || self.addr_conn_map.contains_key(&src)
+    pub fn cleanup_expired_syn(&self, timeout: Duration) {
+        self.flow_map.retain(|_, entry| {
+            let expired = entry.start_time.elapsed() > timeout
+                && entry
+                    .state
+                    .compare_exchange(TcpNatEntryState::SynReceived, TcpNatEntryState::Closed)
+                    .is_ok();
+            if expired {
+                tracing::warn!(?entry, "syn nat entry expired");
+                self.translated_src_map
+                    .remove_if(&entry.translated_src, |_, current| current.id == entry.id);
+            }
+            !expired
+        });
+        self.flow_map.shrink_to_fit();
+        self.translated_src_map.shrink_to_fit();
+    }
+
+    pub fn is_tcp_proxy_flow(&self, src: SocketAddr, mapped_dst: SocketAddr) -> bool {
+        self.flow_map
+            .contains_key(&TcpNatFlowKey { src, mapped_dst })
     }
 
     pub fn list_entries(&self) -> Vec<TcpNatEntrySnapshot> {
         let mut entries = Vec::new();
-        for entry in self.syn_map.iter() {
-            entries.push(entry.value().snapshot());
+        for entry in self.flow_map.iter() {
+            if entry.state() == TcpNatEntryState::SynReceived {
+                entries.push(entry.value().snapshot());
+            }
         }
         for entry in self.conn_map.iter() {
             entries.push(entry.value().snapshot());
@@ -503,6 +620,32 @@ mod tests {
         }
     }
 
+    fn packet_src(packet: &ZCPacket) -> SocketAddrV4 {
+        let ipv4 = Ipv4Packet::new_checked(packet.payload()).unwrap();
+        let tcp = TcpPacket::new_checked(ipv4.payload()).unwrap();
+        SocketAddrV4::new(ipv4.src_addr(), tcp.src_port())
+    }
+
+    fn nic_ctx() -> TcpProxyNicContext {
+        TcpProxyNicContext {
+            local_inet: Some("10.144.144.204/24".parse().unwrap()),
+            local_port: 8899,
+            my_peer_id: 2,
+            smoltcp_enabled: false,
+        }
+    }
+
+    #[test]
+    fn smoltcp_listener_ports_are_unique_per_proxy_mode() {
+        let tcp = TcpProxyMode::Tcp.smoltcp_listener_port();
+        let kcp = TcpProxyMode::KcpSrc.smoltcp_listener_port();
+        let quic = TcpProxyMode::QuicSrc.smoltcp_listener_port();
+
+        assert_ne!(tcp, kcp);
+        assert_ne!(tcp, quic);
+        assert_ne!(kcp, quic);
+    }
+
     #[test]
     fn peer_syn_creates_entry_and_rewrites_to_local_stack() {
         let engine = tcp_engine();
@@ -522,7 +665,7 @@ mod tests {
             "10.144.144.204".parse::<Ipv4Addr>().unwrap()
         );
         let tcp = TcpPacket::new_checked(ipv4.payload()).unwrap();
-        assert_eq!(tcp.src_port(), src.port());
+        assert_ne!(tcp.src_port(), src.port());
         assert_eq!(tcp.dst_port(), 8899);
 
         let entries = engine.list_entries();
@@ -545,25 +688,18 @@ mod tests {
             engine.try_handle_peer_packet(TcpProxyMode::Tcp, &mut request, peer_ctx()),
             TcpProxyPacketAction::Handled { new_syn: true }
         ));
+        let translated_src = packet_src(&request);
         let entry = engine
             .accept_connection(
-                SocketAddr::V4(src),
+                SocketAddr::V4(translated_src),
                 Some("10.144.144.204/24".parse().unwrap()),
             )
             .unwrap();
         assert_eq!(entry.state(), TcpNatEntryState::ConnectingDst);
 
         let local = SocketAddrV4::new("10.144.144.204".parse().unwrap(), 8899);
-        let mut response = build_tcp_packet(local, src, false, true);
-        assert!(engine.try_process_packet_from_nic(
-            &mut response,
-            TcpProxyNicContext {
-                local_inet: Some("10.144.144.204/24".parse().unwrap()),
-                local_port: 8899,
-                my_peer_id: 2,
-                smoltcp_enabled: false,
-            },
-        ));
+        let mut response = build_tcp_packet(local, translated_src, false, true);
+        assert!(engine.try_process_packet_from_nic(&mut response, nic_ctx()));
 
         let hdr: &PeerManagerHeader = response.peer_manager_header().unwrap();
         assert!(hdr.is_no_proxy());
@@ -573,6 +709,111 @@ mod tests {
         let tcp = TcpPacket::new_checked(ipv4.payload()).unwrap();
         assert_eq!(tcp.src_port(), mapped_dst.port());
         assert_eq!(tcp.dst_port(), src.port());
+
+        engine.remove_entry(entry.id());
+        assert!(!engine.is_tcp_proxy_flow(SocketAddr::V4(src), SocketAddr::V4(mapped_dst),));
+        assert!(
+            engine
+                .translated_src_map
+                .get(&SocketAddr::V4(translated_src))
+                .is_none()
+        );
+    }
+
+    #[test]
+    fn same_source_port_to_mapped_and_real_destinations_stay_distinct() {
+        let engine = tcp_engine();
+        let src = SocketAddrV4::new("10.144.144.206".parse().unwrap(), 50000);
+        let mapped_dst = SocketAddrV4::new("10.10.10.42".parse().unwrap(), 80);
+        let real_dst = SocketAddrV4::new("127.0.0.42".parse().unwrap(), 80);
+
+        let mut mapped_request = build_tcp_packet(src, mapped_dst, true, false);
+        assert_eq!(
+            engine.try_handle_peer_packet(TcpProxyMode::Tcp, &mut mapped_request, peer_ctx()),
+            TcpProxyPacketAction::Handled { new_syn: true }
+        );
+        let mapped_translated_src = packet_src(&mapped_request);
+        engine
+            .accept_connection(
+                SocketAddr::V4(mapped_translated_src),
+                Some("10.144.144.204/24".parse().unwrap()),
+            )
+            .unwrap();
+
+        let mut real_request = build_tcp_packet(src, real_dst, true, false);
+        real_request
+            .mut_peer_manager_header()
+            .unwrap()
+            .set_exit_node(true);
+        let mut real_ctx = peer_ctx();
+        real_ctx.enable_exit_node = true;
+        assert_eq!(
+            engine.try_handle_peer_packet(TcpProxyMode::Tcp, &mut real_request, real_ctx),
+            TcpProxyPacketAction::Handled { new_syn: true }
+        );
+        let real_translated_src = packet_src(&real_request);
+        engine
+            .accept_connection(
+                SocketAddr::V4(real_translated_src),
+                Some("10.144.144.204/24".parse().unwrap()),
+            )
+            .unwrap();
+
+        assert_ne!(mapped_translated_src, real_translated_src);
+
+        let local = SocketAddrV4::new("10.144.144.204".parse().unwrap(), 8899);
+        for (translated_src, expected_source) in [
+            (mapped_translated_src, mapped_dst),
+            (real_translated_src, real_dst),
+        ] {
+            let mut response = build_tcp_packet(local, translated_src, false, true);
+            assert!(engine.try_process_packet_from_nic(&mut response, nic_ctx()));
+
+            let ipv4 = Ipv4Packet::new_checked(response.payload()).unwrap();
+            assert_eq!(ipv4.src_addr(), *expected_source.ip());
+            assert_eq!(ipv4.dst_addr(), *src.ip());
+            let tcp = TcpPacket::new_checked(ipv4.payload()).unwrap();
+            assert_eq!(tcp.src_port(), expected_source.port());
+            assert_eq!(tcp.dst_port(), src.port());
+        }
+    }
+
+    #[test]
+    fn clear_discards_accepted_entries_before_restart() {
+        let engine = tcp_engine();
+        let src = SocketAddrV4::new("10.144.144.206".parse().unwrap(), 50000);
+        let mapped_dst = SocketAddrV4::new("10.10.10.42".parse().unwrap(), 80);
+        let mut request = build_tcp_packet(src, mapped_dst, true, false);
+        assert_eq!(
+            engine.try_handle_peer_packet(TcpProxyMode::Tcp, &mut request, peer_ctx()),
+            TcpProxyPacketAction::Handled { new_syn: true }
+        );
+        let old_entry = engine
+            .accept_connection(
+                SocketAddr::V4(packet_src(&request)),
+                Some("10.144.144.204/24".parse().unwrap()),
+            )
+            .unwrap();
+
+        engine.clear();
+
+        assert_eq!(old_entry.state(), TcpNatEntryState::Closed);
+        assert!(engine.flow_map.is_empty());
+        assert!(engine.translated_src_map.is_empty());
+        assert!(engine.conn_map.is_empty());
+
+        let mut retry = build_tcp_packet(src, mapped_dst, true, false);
+        assert_eq!(
+            engine.try_handle_peer_packet(TcpProxyMode::Tcp, &mut retry, peer_ctx()),
+            TcpProxyPacketAction::Handled { new_syn: true }
+        );
+        let new_entry = engine
+            .accept_connection(
+                SocketAddr::V4(packet_src(&retry)),
+                Some("10.144.144.204/24".parse().unwrap()),
+            )
+            .unwrap();
+        assert_ne!(old_entry.id(), new_entry.id());
     }
 
     #[test]
@@ -585,19 +826,264 @@ mod tests {
             engine.try_handle_peer_packet(TcpProxyMode::Tcp, &mut request, peer_ctx()),
             TcpProxyPacketAction::Handled { new_syn: true }
         ));
-        let entry = engine.syn_map.get(&SocketAddr::V4(src)).unwrap().clone();
+        let translated_src = packet_src(&request);
+        let entry = engine
+            .translated_src_map
+            .get(&SocketAddr::V4(translated_src))
+            .unwrap()
+            .clone();
         entry.set_state(TcpNatEntryState::Closed);
 
         assert!(
             engine
                 .accept_connection(
-                    SocketAddr::V4(src),
+                    SocketAddr::V4(translated_src),
                     Some("10.144.144.204/24".parse().unwrap()),
                 )
                 .is_none()
         );
-        assert!(engine.syn_map.get(&SocketAddr::V4(src)).is_none());
-        assert!(engine.addr_conn_map.get(&SocketAddr::V4(src)).is_none());
+        assert!(engine.flow_map.is_empty());
+        assert!(engine.translated_src_map.is_empty());
         assert!(engine.conn_map.is_empty());
     }
+
+    #[test]
+    fn retransmitted_syn_keeps_the_pending_and_accepted_mapping() {
+        let engine = tcp_engine();
+        let src = "10.144.144.206:50000".parse().unwrap();
+        let dst = "10.10.10.42:80".parse().unwrap();
+        let mut first = build_tcp_packet(src, dst, true, false);
+        assert_eq!(
+            engine.try_handle_peer_packet(TcpProxyMode::Tcp, &mut first, peer_ctx()),
+            TcpProxyPacketAction::Handled { new_syn: true }
+        );
+        let translated_src = SocketAddr::V4(packet_src(&first));
+
+        for accepted in [false, true] {
+            if accepted {
+                engine.accept_connection(translated_src, None).unwrap();
+                engine.cleanup_expired_syn(Duration::ZERO);
+            }
+            let mut retry = build_tcp_packet(src, dst, true, false);
+            assert_eq!(
+                engine.try_handle_peer_packet(TcpProxyMode::Tcp, &mut retry, peer_ctx()),
+                TcpProxyPacketAction::Handled { new_syn: false }
+            );
+            assert_eq!(SocketAddr::V4(packet_src(&retry)), translated_src);
+            assert_eq!(engine.flow_map.len(), 1);
+            assert_eq!(engine.translated_src_map.len(), 1);
+            assert_eq!(engine.list_entries().len(), 1);
+        }
+        assert!(engine.accept_connection(translated_src, None).is_none());
+    }
+
+    #[test]
+    fn removing_closing_connection_preserves_replacement_flow() {
+        for state in [
+            TcpNatEntryState::ClosingSrc,
+            TcpNatEntryState::ClosingDst,
+            TcpNatEntryState::Closed,
+        ] {
+            let engine = tcp_engine();
+            let flow = TcpNatFlowKey {
+                src: "10.144.144.206:50000".parse().unwrap(),
+                mapped_dst: "10.10.10.42:80".parse().unwrap(),
+            };
+            let real_dst = "127.0.0.42:80".parse().unwrap();
+            let (old, _) = engine.entry_for_syn(flow, real_dst).unwrap();
+            engine.accept_connection(old.translated_src, None).unwrap();
+            old.set_state(state);
+            let (replacement, new_syn) = engine.entry_for_syn(flow, real_dst).unwrap();
+            assert!(new_syn);
+            assert_ne!(old.translated_src, replacement.translated_src);
+            assert_eq!(engine.translated_src_map.len(), 2);
+
+            engine.remove_entry(old.id());
+            assert!(engine.is_tcp_proxy_flow(flow.src, flow.mapped_dst));
+            assert!(!engine.translated_src_map.contains_key(&old.translated_src));
+            assert_eq!(engine.flow_map.get(&flow).unwrap().id(), replacement.id());
+            assert_eq!(
+                engine
+                    .accept_connection(replacement.translated_src, None)
+                    .unwrap()
+                    .id(),
+                replacement.id()
+            );
+
+            let local = "10.144.144.204:8899".parse().unwrap();
+            let SocketAddr::V4(translated_src) = replacement.translated_src else {
+                unreachable!();
+            };
+            let mut response = build_tcp_packet(local, translated_src, false, true);
+            assert!(engine.try_process_packet_from_nic(&mut response, nic_ctx()));
+            let ip = Ipv4Packet::new_checked(response.payload()).unwrap();
+            let tcp = TcpPacket::new_checked(ip.payload()).unwrap();
+            assert_eq!(SocketAddr::V4(packet_src(&response)), flow.mapped_dst);
+            assert_eq!(tcp.dst_port(), flow.src.port());
+            assert!(ip.verify_checksum());
+            assert!(tcp.verify_checksum(
+                &IpAddress::Ipv4(ip.src_addr()),
+                &IpAddress::Ipv4(ip.dst_addr())
+            ));
+        }
+    }
+
+    #[test]
+    fn expired_syn_releases_both_indices_without_removing_accepted_flow() {
+        let engine = tcp_engine();
+        let pending_flow = TcpNatFlowKey {
+            src: "10.144.144.206:50000".parse().unwrap(),
+            mapped_dst: "10.10.10.42:80".parse().unwrap(),
+        };
+        let accepted_flow = TcpNatFlowKey {
+            mapped_dst: "10.10.10.43:80".parse().unwrap(),
+            ..pending_flow
+        };
+        let real_dst = "127.0.0.42:80".parse().unwrap();
+        let (pending, _) = engine.entry_for_syn(pending_flow, real_dst).unwrap();
+        let (accepted, _) = engine.entry_for_syn(accepted_flow, real_dst).unwrap();
+        engine
+            .accept_connection(accepted.translated_src, None)
+            .unwrap();
+
+        engine.cleanup_expired_syn(Duration::ZERO);
+
+        assert_eq!(pending.state(), TcpNatEntryState::Closed);
+        assert!(
+            engine
+                .accept_connection(pending.translated_src, None)
+                .is_none()
+        );
+        assert!(!engine.is_tcp_proxy_flow(pending_flow.src, pending_flow.mapped_dst));
+        assert!(engine.is_tcp_proxy_flow(accepted_flow.src, accepted_flow.mapped_dst));
+        assert_eq!(engine.translated_src_map.len(), 1);
+        assert_eq!(engine.conn_map.len(), 1);
+        assert_eq!(accepted.state(), TcpNatEntryState::ConnectingDst);
+    }
+
+    #[test]
+    fn translated_port_wrap_skips_live_ports_and_listener() {
+        let engine = tcp_engine();
+        engine.set_local_port(8899);
+        let flow = TcpNatFlowKey {
+            src: "10.144.144.206:50000".parse().unwrap(),
+            mapped_dst: "10.10.10.42:80".parse().unwrap(),
+        };
+        let real_dst = "127.0.0.42:80".parse().unwrap();
+        engine
+            .next_translated_port
+            .store(u16::MAX, Ordering::Relaxed);
+        let last = engine.allocate_entry(flow, real_dst).unwrap();
+        let first = engine.allocate_entry(flow, real_dst).unwrap();
+        assert_eq!(last.translated_src.port(), u16::MAX);
+        assert_eq!(first.translated_src.port(), 1);
+
+        engine
+            .next_translated_port
+            .store(u16::MAX, Ordering::Relaxed);
+        let next = engine.allocate_entry(flow, real_dst).unwrap();
+        assert_eq!(next.translated_src.port(), 2);
+        assert_eq!(
+            engine
+                .translated_src_map
+                .get(&last.translated_src)
+                .unwrap()
+                .id(),
+            last.id()
+        );
+        assert_eq!(
+            engine
+                .translated_src_map
+                .get(&first.translated_src)
+                .unwrap()
+                .id(),
+            first.id()
+        );
+
+        engine.next_translated_port.store(8899, Ordering::Relaxed);
+        let after_listener = engine.allocate_entry(flow, real_dst).unwrap();
+        assert_eq!(after_listener.translated_src.port(), 8900);
+    }
+
+    #[test]
+    fn exhausted_translated_ports_are_isolated_and_reusable_after_cleanup() {
+        let engine = tcp_engine();
+        engine.set_local_port(8899);
+        let src_ip = "10.144.144.206".parse().unwrap();
+        let dst = "10.10.10.42:80".parse().unwrap();
+        let real_dst = "127.0.0.42:80".parse().unwrap();
+        for port in 1..u16::MAX {
+            let flow = TcpNatFlowKey {
+                src: SocketAddr::V4(SocketAddrV4::new(src_ip, port)),
+                mapped_dst: SocketAddr::V4(dst),
+            };
+            assert!(engine.entry_for_syn(flow, real_dst).is_some());
+        }
+        assert_eq!(engine.translated_src_map.len(), usize::from(u16::MAX) - 1);
+        let src = SocketAddrV4::new(src_ip, u16::MAX);
+        let mut exhausted = build_tcp_packet(src, dst, true, false);
+        assert_eq!(
+            engine.try_handle_peer_packet(TcpProxyMode::Tcp, &mut exhausted, peer_ctx()),
+            TcpProxyPacketAction::Drop
+        );
+        assert!(!engine.is_tcp_proxy_flow(SocketAddr::V4(src), SocketAddr::V4(dst)));
+
+        let other_flow = TcpNatFlowKey {
+            src: "10.144.144.207:50000".parse().unwrap(),
+            mapped_dst: SocketAddr::V4(dst),
+        };
+        assert!(engine.entry_for_syn(other_flow, real_dst).is_some());
+
+        let released_addr = SocketAddr::V4(SocketAddrV4::new(src_ip, 1));
+        let released = engine.accept_connection(released_addr, None).unwrap();
+        released.set_state(TcpNatEntryState::Closed);
+        engine.remove_entry(released.id());
+        let mut retry = build_tcp_packet(src, dst, true, false);
+        assert_eq!(
+            engine.try_handle_peer_packet(TcpProxyMode::Tcp, &mut retry, peer_ctx()),
+            TcpProxyPacketAction::Handled { new_syn: true }
+        );
+        assert_eq!(SocketAddr::V4(packet_src(&retry)), released_addr);
+        assert!(engine.accept_connection(released_addr, None).is_some());
+
+        engine.clear();
+        assert!(engine.flow_map.is_empty());
+        assert!(engine.translated_src_map.is_empty());
+        assert!(engine.conn_map.is_empty());
+        assert!(engine.entry_for_syn(other_flow, real_dst).is_some());
+    }
+
+    #[test]
+    fn concurrent_syns_share_one_mapping_and_only_one_accept() {
+        let engine = tcp_engine();
+        let barrier = std::sync::Barrier::new(8);
+        let flow = TcpNatFlowKey {
+            src: "10.144.144.206:50000".parse().unwrap(),
+            mapped_dst: "10.10.10.42:80".parse().unwrap(),
+        };
+        let results = std::thread::scope(|scope| {
+            let tasks: Vec<_> = (0..8)
+                .map(|_| {
+                    scope.spawn(|| {
+                        barrier.wait();
+                        let (entry, new_syn) = engine.entry_for_syn(flow, flow.mapped_dst).unwrap();
+                        let accepted = engine
+                            .accept_connection(entry.translated_src, None)
+                            .is_some();
+                        (entry.id(), new_syn, accepted)
+                    })
+                })
+                .collect();
+            tasks
+                .into_iter()
+                .map(|task| task.join().unwrap())
+                .collect::<Vec<_>>()
+        });
+        assert!(results.iter().all(|result| result.0 == results[0].0));
+        assert_eq!(results.iter().filter(|result| result.1).count(), 1);
+        assert_eq!(results.iter().filter(|result| result.2).count(), 1);
+        assert_eq!(engine.flow_map.len(), 1);
+        assert_eq!(engine.translated_src_map.len(), 1);
+        assert_eq!(engine.conn_map.len(), 1);
+    }
 }

easytier-core/src/gateway/proxy/tcp_proxy_service.rs

@@ -3,7 +3,8 @@ use std::sync::{Arc, Weak, atomic::Ordering};
 use std::time::Duration;
 
 use atomic_shim::AtomicU64;
-use tokio::io::{AsyncWriteExt, copy};
+use parking_lot::Mutex;
+use tokio::io::AsyncWriteExt;
 use tokio::task::JoinSet;
 
 use crate::{
@@ -34,10 +35,10 @@ use crate::gateway::smoltcp::{SmolTcpStack, output_dst_ip};
 fn spawn_tcp_proxy_task(
     lifecycle: &AtomicU64,
     expected_generation: u64,
-    tasks: &std::sync::Mutex<JoinSet<()>>,
+    tasks: &Mutex<JoinSet<()>>,
     task: impl Future<Output = ()> + Send + 'static,
 ) -> bool {
-    let mut tasks = tasks.lock().unwrap();
+    let mut tasks = tasks.lock();
     if lifecycle.load(Ordering::Acquire) != expected_generation {
         return false;
     }
@@ -57,12 +58,12 @@ pub struct TcpProxyService<
     connector: Arc<C>,
     engine: Arc<TcpProxyEngine>,
     mode: TcpProxyMode,
-    peer_pipeline_guard: std::sync::Mutex<Option<PipelineRegistrationGuard>>,
-    nic_pipeline_guard: std::sync::Mutex<Option<PipelineRegistrationGuard>>,
-    kernel_listener: std::sync::Mutex<Option<Arc<F::Listener>>>,
+    peer_pipeline_guard: Mutex<Option<PipelineRegistrationGuard>>,
+    nic_pipeline_guard: Mutex<Option<PipelineRegistrationGuard>>,
+    kernel_listener: Mutex<Option<Arc<F::Listener>>>,
     #[cfg(feature = "proxy-smoltcp-stack")]
-    smoltcp_stack: std::sync::Mutex<Option<Arc<SmolTcpStack>>>,
-    tasks: std::sync::Mutex<JoinSet<()>>,
+    smoltcp_stack: Mutex<Option<Arc<SmolTcpStack>>>,
+    tasks: Mutex<JoinSet<()>>,
     lifecycle: AtomicU64,
 }
 
@@ -86,12 +87,12 @@ impl<R: TcpProxyRuntime + 'static, F: VirtualTcpListenerFactory, C: TcpProxyDest
             connector,
             engine: Arc::new(TcpProxyEngine::new(cidr_table)),
             mode,
-            peer_pipeline_guard: std::sync::Mutex::new(None),
-            nic_pipeline_guard: std::sync::Mutex::new(None),
-            kernel_listener: std::sync::Mutex::new(None),
+            peer_pipeline_guard: Mutex::new(None),
+            nic_pipeline_guard: Mutex::new(None),
+            kernel_listener: Mutex::new(None),
             #[cfg(feature = "proxy-smoltcp-stack")]
-            smoltcp_stack: std::sync::Mutex::new(None),
-            tasks: std::sync::Mutex::new(JoinSet::new()),
+            smoltcp_stack: Mutex::new(None),
+            tasks: Mutex::new(JoinSet::new()),
             lifecycle: AtomicU64::new(0),
         })
     }
@@ -120,6 +121,8 @@ impl<R: TcpProxyRuntime + 'static, F: VirtualTcpListenerFactory, C: TcpProxyDest
             }
         };
 
+        self.engine.clear();
+
         let snapshot = self.runtime.proxy_runtime_snapshot();
         let start_result = if snapshot.smoltcp_enabled {
             #[cfg(feature = "proxy-smoltcp-stack")]
@@ -157,13 +160,15 @@ impl<R: TcpProxyRuntime + 'static, F: VirtualTcpListenerFactory, C: TcpProxyDest
 
     pub fn stop(&self) {
         self.stop_resources();
-        self.tasks.lock().unwrap().abort_all();
+        self.tasks.lock().abort_all();
+        self.engine.clear();
     }
 
     pub(crate) async fn stop_and_wait(&self) {
         self.stop_resources();
-        let mut tasks = std::mem::take(&mut *self.tasks.lock().unwrap());
+        let mut tasks = std::mem::take(&mut *self.tasks.lock());
         tasks.shutdown().await;
+        self.engine.clear();
     }
 
     fn stop_resources(&self) {
@@ -183,17 +188,17 @@ impl<R: TcpProxyRuntime + 'static, F: VirtualTcpListenerFactory, C: TcpProxyDest
                 break;
             }
         }
-        if let Some(guard) = self.peer_pipeline_guard.lock().unwrap().take() {
+        if let Some(guard) = self.peer_pipeline_guard.lock().take() {
             guard.close();
         }
-        if let Some(guard) = self.nic_pipeline_guard.lock().unwrap().take() {
+        if let Some(guard) = self.nic_pipeline_guard.lock().take() {
             guard.close();
         }
-        if let Some(listener) = self.kernel_listener.lock().unwrap().take() {
+        if let Some(listener) = self.kernel_listener.lock().take() {
             drop(listener);
         }
         #[cfg(feature = "proxy-smoltcp-stack")]
-        if let Some(stack) = self.smoltcp_stack.lock().unwrap().take() {
+        if let Some(stack) = self.smoltcp_stack.lock().take() {
             drop(stack);
         }
     }
@@ -204,7 +209,7 @@ impl<R: TcpProxyRuntime + 'static, F: VirtualTcpListenerFactory, C: TcpProxyDest
     }
 
     pub async fn register_peer_pipeline(self: &Arc<Self>) {
-        if self.peer_pipeline_guard.lock().unwrap().is_some() {
+        if self.peer_pipeline_guard.lock().is_some() {
             return;
         }
         let peer_guard = self
@@ -213,11 +218,11 @@ impl<R: TcpProxyRuntime + 'static, F: VirtualTcpListenerFactory, C: TcpProxyDest
                 service: Arc::downgrade(self),
             }))
             .await;
-        self.peer_pipeline_guard.lock().unwrap().replace(peer_guard);
+        self.peer_pipeline_guard.lock().replace(peer_guard);
     }
 
     pub async fn register_nic_pipeline(self: &Arc<Self>) {
-        if self.nic_pipeline_guard.lock().unwrap().is_some() {
+        if self.nic_pipeline_guard.lock().is_some() {
             return;
         }
         let nic_guard = self
@@ -226,7 +231,7 @@ impl<R: TcpProxyRuntime + 'static, F: VirtualTcpListenerFactory, C: TcpProxyDest
                 service: Arc::downgrade(self),
             }))
             .await;
-        self.nic_pipeline_guard.lock().unwrap().replace(nic_guard);
+        self.nic_pipeline_guard.lock().replace(nic_guard);
     }
 
     fn spawn_syn_cleanup(self: &Arc<Self>, generation: u64) {
@@ -244,7 +249,7 @@ impl<R: TcpProxyRuntime + 'static, F: VirtualTcpListenerFactory, C: TcpProxyDest
     }
 
     fn drain_completed_tasks(&self) {
-        let mut tasks = self.tasks.lock().unwrap();
+        let mut tasks = self.tasks.lock();
         while let Some(result) = tasks.try_join_next() {
             if let Err(err) = result {
                 tracing::warn!(?err, "tcp proxy task finished with error");
@@ -262,6 +267,7 @@ impl<R: TcpProxyRuntime + 'static, F: VirtualTcpListenerFactory, C: TcpProxyDest
             .bind_tcp(
                 TcpListenOptions::proxy_nat(listen_addr).with_bind(
                     TcpBindOptions::default()
+                        .with_need_protect(false)
                         .with_context(
                             self.socket_context
                                 .clone()
@@ -272,10 +278,7 @@ impl<R: TcpProxyRuntime + 'static, F: VirtualTcpListenerFactory, C: TcpProxyDest
             )
             .await?;
         self.engine.set_local_port(listener.local_addr()?.port());
-        self.kernel_listener
-            .lock()
-            .unwrap()
-            .replace(listener.clone());
+        self.kernel_listener.lock().replace(listener.clone());
 
         let service = Arc::downgrade(self);
         let _ = spawn_tcp_proxy_task(&self.lifecycle, generation, &self.tasks, async move {
@@ -308,7 +311,7 @@ impl<R: TcpProxyRuntime + 'static, F: VirtualTcpListenerFactory, C: TcpProxyDest
             .local_inet
             .map(|inet| inet.address())
             .unwrap_or(std::net::Ipv4Addr::new(192, 88, 99, 254));
-        let stack = SmolTcpStack::new(local_ip).await?;
+        let stack = SmolTcpStack::new(local_ip, self.mode.smoltcp_listener_port()).await?;
         self.engine.set_local_port(stack.local_port());
 
         let mut output_rx = stack.take_output_rx().await?;
@@ -349,7 +352,7 @@ impl<R: TcpProxyRuntime + 'static, F: VirtualTcpListenerFactory, C: TcpProxyDest
             }
         });
 
-        self.smoltcp_stack.lock().unwrap().replace(stack);
+        self.smoltcp_stack.lock().replace(stack);
         Ok(())
     }
 
@@ -428,7 +431,7 @@ impl<R: TcpProxyRuntime + 'static, F: VirtualTcpListenerFactory, C: TcpProxyDest
             entry.set_state(TcpNatEntryState::Connected);
         }
 
-        let ret = copy_bidirectional_no_shutdown(src_stream.as_mut(), dst_stream.as_mut()).await;
+        let ret = copy_bidirectional(src_stream.as_mut(), dst_stream.as_mut()).await;
         tracing::info!(nat_entry = ?entry, ret = ?ret, "nat tcp connection closed");
 
         entry.set_state(TcpNatEntryState::ClosingSrc);
@@ -461,9 +464,11 @@ impl<R: TcpProxyRuntime + 'static, F: VirtualTcpListenerFactory, C: TcpProxyDest
                 smoltcp_enabled: snapshot.smoltcp_enabled,
             },
         );
-        let TcpProxyPacketAction::Handled { new_syn: _new_syn } = action else {
-            return Some(packet);
-        };
+        match action {
+            TcpProxyPacketAction::Handled { new_syn: _ } => {}
+            TcpProxyPacketAction::Drop => return None,
+            TcpProxyPacketAction::Pass => return Some(packet),
+        }
 
         if snapshot.smoltcp_enabled {
             #[cfg(feature = "proxy-smoltcp-stack")]
@@ -485,7 +490,7 @@ impl<R: TcpProxyRuntime + 'static, F: VirtualTcpListenerFactory, C: TcpProxyDest
 
     #[cfg(feature = "proxy-smoltcp-stack")]
     async fn handle_smoltcp_packet(&self, packet: ZCPacket) {
-        let stack = self.smoltcp_stack.lock().unwrap().clone();
+        let stack = self.smoltcp_stack.lock().clone();
         let Some(stack) = stack else {
             tracing::error!("smoltcp stack is not started");
             return;
@@ -509,24 +514,13 @@ impl<R: TcpProxyRuntime + 'static, F: VirtualTcpListenerFactory, C: TcpProxyDest
     }
 }
 
-async fn copy_bidirectional_no_shutdown(
+async fn copy_bidirectional(
     src: &mut dyn TcpProxyStream,
     dst: &mut dyn TcpProxyStream,
 ) -> Result<(), ProxyRuntimeError> {
-    let (mut src_reader, mut src_writer) = tokio::io::split(src);
-    let (mut dst_reader, mut dst_writer) = tokio::io::split(dst);
-    let src_to_dst = copy(&mut src_reader, &mut dst_writer);
-    let dst_to_src = copy(&mut dst_reader, &mut src_writer);
-    tokio::pin!(src_to_dst);
-    tokio::pin!(dst_to_src);
-    tokio::select! {
-        result = &mut src_to_dst => {
-            result?;
-        }
-        result = &mut dst_to_src => {
-            result?;
-        }
-    }
+    // Forward EOF to the opposite writer while continuing to relay its reply.
+    // Returning on the first EOF would discard responses to half-closed requests.
+    tokio::io::copy_bidirectional(src, dst).await?;
     Ok(())
 }
 
@@ -574,6 +568,57 @@ impl<R: TcpProxyRuntime + 'static, F: VirtualTcpListenerFactory, C: TcpProxyDest
 mod tests {
     use super::*;
     use std::sync::atomic::AtomicBool;
+    use tokio::io::AsyncReadExt;
+
+    async fn response_after_half_close(source_closes_first: bool, request_size: usize) {
+        // Small buffers force the relay to make progress in both directions;
+        // the response is deliberately larger than either relay buffer.
+        let (mut client, mut src) = tokio::io::duplex(64);
+        let (mut dst, mut server) = tokio::io::duplex(64);
+        let request = vec![0x35; request_size];
+        let response = vec![0xa7; 64 * 1024];
+        let relay = async {
+            if source_closes_first {
+                copy_bidirectional(&mut src, &mut dst).await
+            } else {
+                copy_bidirectional(&mut dst, &mut src).await
+            }
+            .unwrap();
+        };
+        let requester = async {
+            client.write_all(&request).await.unwrap();
+            client.shutdown().await.unwrap();
+            let mut received = Vec::new();
+            client.read_to_end(&mut received).await.unwrap();
+            assert_eq!(received, response);
+        };
+        let responder = async {
+            let mut received = Vec::new();
+            server.read_to_end(&mut received).await.unwrap();
+            assert_eq!(received, request);
+            server.write_all(&response).await.unwrap();
+            server.shutdown().await.unwrap();
+        };
+        timeout(Duration::from_secs(5), async {
+            tokio::join!(relay, requester, responder);
+        })
+        .await
+        .expect("half-closed relay did not finish");
+    }
+
+    #[tokio::test]
+    async fn source_half_close_preserves_response() {
+        for request_size in [0, 32 * 1024] {
+            response_after_half_close(true, request_size).await;
+        }
+    }
+
+    #[tokio::test]
+    async fn destination_half_close_preserves_response() {
+        for request_size in [0, 32 * 1024] {
+            response_after_half_close(false, request_size).await;
+        }
+    }
 
     struct DropSignal(Arc<AtomicBool>);
 
@@ -594,7 +639,7 @@ mod tests {
     #[tokio::test]
     async fn stop_fence_linearizes_task_registration() {
         let lifecycle = AtomicU64::new(1);
-        let tasks = std::sync::Mutex::new(JoinSet::new());
+        let tasks = Mutex::new(JoinSet::new());
         let accepted_dropped = Arc::new(AtomicBool::new(false));
 
         assert!(spawn_tcp_proxy_task(
@@ -604,7 +649,7 @@ mod tests {
             pending_task(accepted_dropped.clone()),
         ));
         lifecycle.store(2, Ordering::Release);
-        let mut stopping = std::mem::take(&mut *tasks.lock().unwrap());
+        let mut stopping = std::mem::take(&mut *tasks.lock());
         stopping.shutdown().await;
         assert!(accepted_dropped.load(Ordering::Acquire));
 
@@ -626,7 +671,7 @@ mod tests {
             &tasks,
             pending_task(current_dropped.clone()),
         ));
-        let mut current = std::mem::take(&mut *tasks.lock().unwrap());
+        let mut current = std::mem::take(&mut *tasks.lock());
         current.shutdown().await;
         assert!(current_dropped.load(Ordering::Acquire));
     }

easytier-core/src/gateway/proxy/wrapped_tcp_proxy.rs

@@ -128,11 +128,11 @@ pub struct WrappedTcpProxyNicContext {
 pub async fn try_process_wrapped_tcp_packet_from_nic<ConnectionLookup, AllowCheck, AllowCheckFut>(
     zc_packet: &mut ZCPacket,
     ctx: WrappedTcpProxyNicContext,
-    is_tcp_proxy_connection: ConnectionLookup,
+    is_tcp_proxy_flow: ConnectionLookup,
     check_dst_allowed: AllowCheck,
 ) -> bool
 where
-    ConnectionLookup: Fn(SocketAddr) -> bool,
+    ConnectionLookup: Fn(SocketAddr, SocketAddr) -> bool,
     AllowCheck: FnOnce(Ipv4Addr) -> AllowCheckFut,
     AllowCheckFut: Future<Output = bool>,
 {
@@ -156,9 +156,14 @@ where
     let src_ip = ip_packet.src_addr();
     let dst_ip = ip_packet.dst_addr();
     let src_port = tcp_packet.src_port();
+    let dst_port = tcp_packet.dst_port();
     let is_syn = tcp_packet.syn() && !tcp_packet.ack();
 
     if is_syn {
+        // Own virtual IP traffic must stay local; it can never reach a peer.
+        if ctx.local_ipv4 == Some(dst_ip) {
+            return false;
+        }
         if !check_dst_allowed(dst_ip).await {
             tracing::warn!(
                 ?ctx.transport,
@@ -167,7 +172,10 @@ where
             );
             return false;
         }
-    } else if !is_tcp_proxy_connection(SocketAddr::V4(SocketAddrV4::new(src_ip, src_port))) {
+    } else if !is_tcp_proxy_flow(
+        SocketAddr::V4(SocketAddrV4::new(src_ip, src_port)),
+        SocketAddr::V4(SocketAddrV4::new(dst_ip, dst_port)),
+    ) {
         return false;
     }
 
@@ -362,7 +370,7 @@ mod tests {
             try_process_wrapped_tcp_packet_from_nic(
                 &mut packet,
                 context(WrappedTcpProxyTransport::Kcp),
-                |_| false,
+                |_, _| false,
                 |_| async { true },
             )
             .await
@@ -383,7 +391,7 @@ mod tests {
             !try_process_wrapped_tcp_packet_from_nic(
                 &mut packet,
                 context(WrappedTcpProxyTransport::Kcp),
-                |_| false,
+                |_, _| false,
                 |_| async { false },
             )
             .await
@@ -403,7 +411,9 @@ mod tests {
             try_process_wrapped_tcp_packet_from_nic(
                 &mut packet,
                 context(WrappedTcpProxyTransport::Quic),
-                |addr| addr == SocketAddr::V4(src),
+                |src_addr, dst_addr| {
+                    src_addr == SocketAddr::V4(src) && dst_addr == SocketAddr::V4(dst)
+                },
                 |_| async { false },
             )
             .await
@@ -424,7 +434,7 @@ mod tests {
             !try_process_wrapped_tcp_packet_from_nic(
                 &mut packet,
                 context(WrappedTcpProxyTransport::Quic),
-                |_| false,
+                |_, _| false,
                 |_| async { true },
             )
             .await
@@ -441,10 +451,39 @@ mod tests {
             !try_process_wrapped_tcp_packet_from_nic(
                 &mut packet,
                 context(WrappedTcpProxyTransport::Kcp),
-                |_| false,
+                |_, _| false,
                 |_| async { true },
             )
             .await
         );
     }
+
+    #[tokio::test]
+    async fn own_virtual_ip_syn_is_not_marked() {
+        let own_ip = "10.144.144.204".parse().unwrap();
+        let src = SocketAddrV4::new(own_ip, 50000);
+        let dst = SocketAddrV4::new(own_ip, 80);
+
+        for transport in [
+            WrappedTcpProxyTransport::Kcp,
+            WrappedTcpProxyTransport::Quic,
+        ] {
+            let mut packet = build_tcp_packet(src, dst, true, false);
+
+            assert!(
+                !try_process_wrapped_tcp_packet_from_nic(
+                    &mut packet,
+                    context(transport),
+                    |_, _| false,
+                    |_| async { true },
+                )
+                .await
+            );
+
+            assert_eq!(
+                packet.peer_manager_header().unwrap().packet_type,
+                PacketType::Data as u8
+            );
+        }
+    }
 }

easytier-core/src/gateway/proxy/wrapped_transport/packet_plane.rs

@@ -257,10 +257,10 @@ where
                     WrappedTransportKind::Quic => WrappedTcpProxyTransport::Quic,
                 },
                 my_peer_id: self.peer_manager.my_peer_id(),
-                local_ipv4: snapshot.local_inet.map(|inet| inet.address()),
+                local_ipv4: snapshot.virtual_ipv4,
                 smoltcp_enabled: snapshot.smoltcp_enabled,
             },
-            move |src| connection_engine.is_tcp_proxy_connection(src),
+            move |src, mapped_dst| connection_engine.is_tcp_proxy_flow(src, mapped_dst),
             move |dst_ip| async move {
                 match transport {
                     WrappedTransportKind::Kcp => {

easytier-core/src/gateway/smoltcp/stack.rs

@@ -11,6 +11,7 @@ use crate::gateway::proxy::traits::TcpProxyStream;
 
 pub struct SmolTcpStack {
     ingress_tx: mpsc::Sender<ZCPacket>,
+    local_port: u16,
     output_rx: Mutex<Option<mpsc::Receiver<Vec<u8>>>>,
     listener: Mutex<TcpListener>,
     _net: Net,
@@ -18,7 +19,7 @@ pub struct SmolTcpStack {
 }
 
 impl SmolTcpStack {
-    pub async fn new(local_ip: Ipv4Addr) -> anyhow::Result<Arc<Self>> {
+    pub async fn new(local_ip: Ipv4Addr, local_port: u16) -> anyhow::Result<Arc<Self>> {
         let tasks = Arc::new(std::sync::Mutex::new(JoinSet::new()));
         let mut cap = smoltcp::phy::DeviceCapabilities::default();
         cap.max_transmission_unit = 1280;
@@ -63,12 +64,13 @@ impl SmolTcpStack {
         );
         net.set_any_ip(true);
         let listener = net
-            .tcp_bind("0.0.0.0:8899".parse().unwrap())
+            .tcp_bind(SocketAddr::new(Ipv4Addr::UNSPECIFIED.into(), local_port))
             .await
             .map_err(|error| anyhow::anyhow!("bind smoltcp listener failed: {error}"))?;
 
         Ok(Arc::new(Self {
             ingress_tx,
+            local_port,
             output_rx: Mutex::new(Some(stack_stream)),
             listener: Mutex::new(listener),
             _net: net,
@@ -77,7 +79,7 @@ impl SmolTcpStack {
     }
 
     pub fn local_port(&self) -> u16 {
-        8899
+        self.local_port
     }
 
     pub async fn send_ingress(&self, packet: ZCPacket) -> anyhow::Result<()> {
@@ -137,12 +139,12 @@ mod tests {
     };
 
     const LOCAL_ADDR: Ipv4Address = Ipv4Address::new(192, 88, 99, 254);
-    const LOCAL_PORT: u16 = 8899;
+    const LOCAL_PORT: u16 = 8900;
     const PACKETS: TcpPackets = TcpPackets::new(LOCAL_ADDR, LOCAL_PORT);
 
     #[tokio::test]
     async fn accepts_concurrent_connections_with_one_logical_listener() {
-        let stack = SmolTcpStack::new(LOCAL_ADDR).await.unwrap();
+        let stack = SmolTcpStack::new(LOCAL_ADDR, LOCAL_PORT).await.unwrap();
         let mut output = stack.take_output_rx().await.unwrap();
         let client_addr = Ipv4Address::new(192, 88, 99, 1);
 

easytier-core/src/gateway/smoltcp/tokio_smoltcp/socket.rs

@@ -199,11 +199,14 @@ impl AsyncWrite for TcpStream {
     fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), io::Error>> {
         let mut socket = self.reactor.get_socket::<tcp::Socket>(*self.handle);
 
-        if socket.is_open() {
+        if socket.may_send() {
             socket.close();
             self.reactor.notify();
         }
-        if socket.state() == tcp::State::Closed {
+        if matches!(
+            socket.state(),
+            tcp::State::FinWait2 | tcp::State::TimeWait | tcp::State::Closed
+        ) {
             return Poll::Ready(Ok(()));
         }
 

easytier-core/src/gateway/socks5/host.rs

@@ -67,6 +67,7 @@ where
 
     fn udp_bind_options(&self) -> UdpBindOptions {
         UdpBindOptions::socks5()
+            .with_need_protect(false)
             .with_context(self.socket_context.clone().with_ip_version(IpVersion::V6))
             .with_local_addr(Some(SocketAddr::V6(SocketAddrV6::new(
                 Ipv6Addr::UNSPECIFIED,
@@ -289,6 +290,10 @@ mod tests {
         );
         assert_eq!(options[0].context.socket_mark, context.socket_mark);
         assert_eq!(options[0].context.ip_version, IpVersion::V6);
+        assert!(
+            !options[0].need_protect,
+            "SOCKS5 association socket is inbound"
+        );
     }
 
     #[tokio::test]