Add proxy subscription runtime support

Add daemon RPCs, Apple and GTK import flows, packet proxy runtime support, diagnostics, and BEPs for proxy subscription handling.

Redact subscription URL secrets from fetch errors before they reach logs or UI surfaces.
This commit is contained in:
JettChenT 2026-06-01 15:23:17 +08:00
parent 97c569fb35
commit d1638726ca
46 changed files with 15079 additions and 456 deletions

View file

@ -0,0 +1,110 @@
# `BEP-0011` - Mihomo-Compatible Trojan Runtime
```text
Status: Draft
Proposal: BEP-0011
Authors: Codex
Coordinator: Jett Chen
Reviewers: Pending
Constitution Sections: 2, 4, 5
Implementation PRs: Pending
Decision Date: Pending
```
## Summary
Burrow's proxy subscription runtime should match Mihomo's Trojan wire behavior
for imported nodes wherever Burrow already claims runtime support. This proposal
covers TCP Trojan nodes in the packet tunnel runtime: ALPN defaults, DNS-backed
hostname preservation, UDP gating, UDP packet fragmentation, certificate
pinning, and diagnostics for Mihomo-only TLS fingerprint behavior.
The goal is compatibility without overstating support. Burrow should apply
Mihomo semantics that can be implemented correctly today, and it should make
unsupported Mihomo features visible instead of silently pretending to support
them.
## Motivation
- Imported Trojan subscriptions commonly target Mihomo-compatible clients.
- A stored node can carry `client-fingerprint`, ALPN, UDP, and certificate
pinning metadata that materially changes whether the proxy server accepts the
connection.
- Burrow previously flattened absent ALPN and explicit empty ALPN into the same
value, ignored Trojan UDP enablement, rejected oversized Trojan UDP payloads
instead of fragmenting them, and stored certificate pins without enforcing
them.
## Detailed Design
- Store an `alpn_present` marker alongside the existing Trojan `alpn` vector.
Missing ALPN uses Mihomo's TCP Trojan default `h2,http/1.1`; explicit ALPN,
including an explicit empty YAML list, is honored as written.
- Store Trojan `udp`. URI imports default to enabled to match Mihomo's URI
converter. YAML imports default to disabled unless `udp` is present.
- Point proxy-network DNS at the daemon-owned tunnel address. The packet runtime
answers A queries with fake IPs, records fake-IP to hostname mappings, and
uses hostname-form SOCKS addresses in Trojan TCP requests when a later TCP
flow targets one of those fake IPs.
- Enforce Trojan UDP gating at runtime and fragment UDP payloads above 8192
bytes into multiple Trojan UDP frames.
- Treat `fingerprint` as SHA-256 certificate pinning. Browser fingerprint names
are rejected in `fingerprint` with guidance to use `client-fingerprint`.
- Keep using rustls for non-Apple TLS and OpenSSL for the macOS Trojan TLS path.
`client-fingerprint` is logged when present because Mihomo's uTLS ClientHello
impersonation is not implemented in Burrow yet.
- Coalesce the Trojan request header into one TLS write, matching Mihomo's
`trojan.WriteHeader` behavior.
- Continue rejecting Trojan `ws` and `grpc` at runtime until those transports
are implemented with their complete TLS and framing behavior.
## Security and Operational Considerations
- Certificate pinning changes TLS verification semantics. When a pin is
configured, Burrow verifies the presented chain against the pin instead of the
WebPKI root store, matching Mihomo's pinning model.
- The runtime must not log proxy passwords or subscription tokens.
- uTLS/browser fingerprinting should not be faked with partial ClientHello
tweaks. Until Burrow has a complete implementation, the runtime should say
that it is using platform TLS rather than a Mihomo uTLS impersonation.
- Rollback is a code rollback plus re-importing any subscriptions whose stored
JSON schema has changed during testing.
## Contributor Playbook
1. Compare Burrow behavior against `/Users/jettchen/dev/vpn-ref/mihomo` before
changing protocol details.
2. Run `cargo fmt -p burrow`.
3. Run `cargo test -p burrow proxy_subscription::tests::`.
4. Run `cargo test -p burrow proxy_runtime::tests::`.
5. Run `cargo check -p burrow`.
6. For live validation, use a Trojan node with omitted ALPN and
`client-fingerprint: chrome`; confirm the logs show Mihomo default ALPN, the
physical-interface bind, the macOS OpenSSL handshake, and the platform TLS
fingerprint warning.
## Alternatives Considered
- Implement full uTLS immediately. Rejected for this change because rustls does
not expose enough ClientHello control, and adding a second TLS stack needs
separate review for Apple builds and static library consumers.
- Treat all empty ALPN vectors as explicit empty ALPN. Rejected because older
Burrow imports already stored omitted URI ALPN as `[]`, which would preserve
the compatibility bug.
- Ignore `fingerprint` until uTLS exists. Rejected because certificate pinning
is independent of browser ClientHello impersonation.
## Impact on Other Work
- BEP-0010 remains the packet tunnel direction for proxy subscriptions.
- A future BEP or revision should cover uTLS/browser fingerprint support,
websocket Trojan, gRPC Trojan, and daemon-owned proxy-server DNS resolution.
## Decision
Pending review.
## References
- `docs/trojan-mihomo-discrepancies.md`
- `evolution/proposals/BEP-0010-proxy-subscriptions-as-packet-tunnel-networks.md`