trusttunnel/trusttunnel

Purpose and Workspace Layout

TrustTunnel is the server-side VPN endpoint for a protocol designed to resemble ordinary HTTPS traffic. It accepts client tunnels over HTTP/1.1, HTTP/2, or QUIC, authenticates and filters them, then forwards TCP, UDP, and ICMP traffic to target networks. The Rust workspace separates endpoint executable, shared protocol/runtime library, deep-link codec, setup tooling, and procedural macros: Cargo.toml, endpoint/Cargo.toml, lib/Cargo.toml.

Runtime Entry Points

The endpoint process starts in endpoint/src/main.rs, loading endpoint and TLS-host configuration, listening for inbound traffic, and supporting client configuration export. The reusable network server runtime is exposed through lib/src/lib.rs and coordinated by lib/src/core.rs. Deployment supports native system services and containers via scripts/trusttunnel.service.template, Dockerfile, and docker-compose.yml.

Listener and Protocol Classification

Inbound encrypted traffic enters TLS-aware listening and is classified before tunnel handling. TLS listener/demultiplexing components establish the boundary between externally HTTPS-like traffic and TrustTunnel protocol streams: lib/src/tls_listener.rs, lib/src/tls_demultiplexer.rs, lib/src/http_demultiplexer.rs. Protocol-specific codecs handle HTTP/1, HTTP/2, HTTP/3/QUIC, datagrams, UDP, and ICMP encapsulation: lib/src/http1_codec.rs, lib/src/http2_codec.rs, lib/src/http3_codec.rs.

Tunnel Session and Security Controls

Tunnel lifecycle and multiplexing are centered on lib/src/tunnel.rs and lib/src/quic_multiplexer.rs. Authentication is registry/credential based, while certificate verification and client-random-prefix rules act as admission controls: lib/src/authentication/registry_based.rs, lib/src/cert_verification.rs, lib/src/rules.rs. Connection limiting and coordinated shutdown protect endpoint capacity and lifecycle: lib/src/connection_limiter.rs, lib/src/shutdown.rs.

Traffic Forwarding Plane

After admission, protocol payloads are converted into outbound flows. TCP, UDP, and ICMP have dedicated forwarding paths: lib/src/tcp_forwarder.rs, lib/src/udp_forwarder.rs, lib/src/icmp_forwarder.rs. Pipes and datagram abstractions bridge tunnel streams to sockets, while direct and SOCKS5 forwarding provide alternate egress mechanisms: lib/src/pipe.rs, lib/src/datagram_pipe.rs, lib/src/socks5_forwarder.rs. Reverse-proxy and HTTP downstream paths support HTTP-oriented endpoint behavior: lib/src/reverse_proxy.rs, lib/src/http_downstream.rs.

Configuration and Client Provisioning

Settings, TLS host definitions, authentication data, and filtering rules are file-backed endpoint boundaries represented in lib/src/settings.rs, lib/src/client_config.rs, and lib/src/rules.rs. The setup wizard interactively composes those files and can obtain/manage certificate setup through ACME: tools/setup_wizard/main.rs, tools/setup_wizard/composer.rs, tools/setup_wizard/acme.rs. Let’s Encrypt is the principal external certificate service.

Client Configuration Encoding and Operations

The endpoint emits either TOML-compatible client settings or compact tt:// deep links. The dedicated codec crate implements encoding, decoding, certificate handling, and wire primitives: deeplink/src/encode.rs, deeplink/src/decode.rs, deeplink/src/cert.rs. Metrics are produced by lib/src/metrics.rs; operational documentation and release/container workflows indicate Linux/macOS native deployment plus Docker and Docker Hub distribution: METRICS.md, .github/workflows/deploy-dockerhub.yml, .github/workflows/build-and-deploy-release.yml.