d1638726ca
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.
110 lines
4.9 KiB
Markdown
110 lines
4.9 KiB
Markdown
# `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`
|