# trusttunnel/trusttunnel architecture

> Architecture diagram of the GitHub repository trusttunnel/trusttunnel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/trusttunnel/trusttunnel
- Repository: https://github.com/trusttunnel/trusttunnel

## Overview

#### 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`.

Main entry points: [`lib/src/authentication/registry_based.rs`](https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/authentication/registry_based.rs) (Admission controls), [`lib/src/core.rs`](https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/core.rs) (Server core), [`endpoint/src/main.rs`](https://github.com/trusttunnel/trusttunnel/blob/master/endpoint/src/main.rs) (Endpoint executable), [`lib/src/http_demultiplexer.rs`](https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/http_demultiplexer.rs) (HTTP demultiplexer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_endpoint["Endpoint runtime"]
  node_endpoint_main["Endpoint executable<br/>Rust binary<br/>[main.rs]"]
  node_server_core["Server core<br/>runtime coordinator<br/>[core.rs]"]
  node_settings["Settings and client config<br/>file-backed settings<br/>[settings.rs]"]
  node_limits_shutdown["Capacity and shutdown<br/>lifecycle controls"]
end

subgraph group_ingress["Ingress and tunnel"]
  node_tls_listener["TLS listener<br/>encrypted ingress<br/>[tls_listener.rs]"]
  node_tls_demux{{"TLS demultiplexer<br/>protocol classifier"}}
  node_http_demux{{"HTTP demultiplexer<br/>HTTP classifier"}}
  node_http_codecs["HTTP tunnel codecs<br/>HTTP/1, HTTP/2, HTTP/3<br/>[http3_codec.rs]"]
  node_tunnel["Tunnel sessions<br/>session lifecycle<br/>[tunnel.rs]"]
  node_quic_mux["QUIC multiplexer<br/>QUIC session transport"]
  node_admission["Admission controls<br/>auth and verification<br/>[registry_based.rs]"]
end

subgraph group_egress["Forwarding plane"]
  node_tcp_forwarder["TCP forwarding<br/>egress forwarder<br/>[tcp_forwarder.rs]"]
  node_udp_forwarder["UDP forwarding<br/>egress forwarder<br/>[udp_forwarder.rs]"]
  node_icmp_forwarder["ICMP forwarding<br/>egress forwarder<br/>[icmp_forwarder.rs]"]
  node_socks5["SOCKS5 forwarding<br/>alternate egress"]
  node_http_downstream["HTTP downstream<br/>HTTP egress<br/>[reverse_proxy.rs]"]
end

subgraph group_provisioning["Provisioning and operations"]
  node_deeplink_codec["Deep-link codec<br/>tt:// codec<br/>[encode.rs]"]
  node_setup_wizard["Setup wizard<br/>interactive provisioning<br/>[main.rs]"]
  node_acme(("Let's Encrypt<br/>external certificate service"))
  node_metrics["Metrics<br/>observability<br/>[metrics.rs]"]
end

node_endpoint_main -->|"loads"| node_settings
node_endpoint_main -->|"starts"| node_server_core
node_server_core -->|"accepts inbound traffic"| node_tls_listener
node_server_core -->|"governed by"| node_limits_shutdown
node_tls_listener -->|"encrypted connections"| node_tls_demux
node_tls_demux -->|"HTTP traffic"| node_http_demux
node_http_demux -->|"HTTP/1-3 tunnels"| node_http_codecs
node_http_codecs -->|"decoded streams"| node_tunnel
node_http_codecs -->|"QUIC transport"| node_quic_mux
node_quic_mux -->|"multiplexed flows"| node_tunnel
node_tunnel -->|"authenticates"| node_admission
node_admission -->|"admitted TCP"| node_tcp_forwarder
node_admission -->|"admitted UDP"| node_udp_forwarder
node_admission -->|"admitted ICMP"| node_icmp_forwarder
node_tcp_forwarder -.->|"optional proxy egress"| node_socks5
node_http_demux -->|"HTTP downstream"| node_http_downstream
node_settings -->|"credentials and rules"| node_admission
node_setup_wizard -->|"writes configuration"| node_settings
node_setup_wizard -->|"obtains certificates"| node_acme
node_endpoint_main -->|"exports client links"| node_deeplink_codec
node_server_core -->|"emits"| node_metrics

click node_endpoint_main "https://github.com/trusttunnel/trusttunnel/blob/master/endpoint/src/main.rs"
click node_server_core "https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/core.rs"
click node_settings "https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/settings.rs"
click node_tls_listener "https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/tls_listener.rs"
click node_tls_demux "https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/tls_demultiplexer.rs"
click node_http_demux "https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/http_demultiplexer.rs"
click node_http_codecs "https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/http3_codec.rs"
click node_tunnel "https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/tunnel.rs"
click node_quic_mux "https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/quic_multiplexer.rs"
click node_admission "https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/authentication/registry_based.rs"
click node_limits_shutdown "https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/connection_limiter.rs"
click node_tcp_forwarder "https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/tcp_forwarder.rs"
click node_udp_forwarder "https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/udp_forwarder.rs"
click node_icmp_forwarder "https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/icmp_forwarder.rs"
click node_socks5 "https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/socks5_forwarder.rs"
click node_http_downstream "https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/reverse_proxy.rs"
click node_deeplink_codec "https://github.com/trusttunnel/trusttunnel/blob/master/deeplink/src/encode.rs"
click node_setup_wizard "https://github.com/trusttunnel/trusttunnel/blob/master/tools/setup_wizard/main.rs"
click node_metrics "https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/metrics.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_endpoint_main,node_server_core,node_settings,node_limits_shutdown toneBlue
class node_tls_listener,node_tls_demux,node_http_demux,node_http_codecs,node_tunnel,node_quic_mux,node_admission toneAmber
class node_tcp_forwarder,node_udp_forwarder,node_icmp_forwarder,node_socks5,node_http_downstream toneMint
class node_deeplink_codec,node_setup_wizard,node_acme,node_metrics toneRose
```

## Components

### Endpoint runtime

- [Endpoint executable](https://github.com/trusttunnel/trusttunnel/blob/master/endpoint/src/main.rs): Rust binary · Loads endpoint configuration, listens, and exports client configuration. · `endpoint/src/main.rs`
- [Server core](https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/core.rs): runtime coordinator · Coordinates the reusable endpoint network server. · `lib/src/core.rs`
- [Settings and client config](https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/settings.rs): file-backed settings · Defines endpoint settings, TLS hosts, and client configuration. · `lib/src/settings.rs`
- [Capacity and shutdown](https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/connection_limiter.rs): lifecycle controls · Limits connections and coordinates graceful shutdown. · `lib/src/connection_limiter.rs`

### Ingress and tunnel

- [TLS listener](https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/tls_listener.rs): encrypted ingress · `lib/src/tls_listener.rs`
- [TLS demultiplexer](https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/tls_demultiplexer.rs): protocol classifier · Separates HTTPS-like traffic from TrustTunnel streams. · `lib/src/tls_demultiplexer.rs`
- [HTTP demultiplexer](https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/http_demultiplexer.rs): HTTP classifier · `lib/src/http_demultiplexer.rs`
- [HTTP tunnel codecs](https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/http3_codec.rs): HTTP/1, HTTP/2, HTTP/3 · Encapsulates tunnel streams and datagrams across HTTP transports. · `lib/src/http3_codec.rs`
- [Tunnel sessions](https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/tunnel.rs): session lifecycle · Owns tunnel lifecycle and multiplexed traffic handling. · `lib/src/tunnel.rs`
- [QUIC multiplexer](https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/quic_multiplexer.rs): QUIC session transport · `lib/src/quic_multiplexer.rs`
- [Admission controls](https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/authentication/registry_based.rs): auth and verification · Applies registry credentials, certificate verification, and client-prefix rules. · `lib/src/authentication/registry_based.rs`

### Forwarding plane

- [TCP forwarding](https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/tcp_forwarder.rs): egress forwarder · `lib/src/tcp_forwarder.rs`
- [UDP forwarding](https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/udp_forwarder.rs): egress forwarder · `lib/src/udp_forwarder.rs`
- [ICMP forwarding](https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/icmp_forwarder.rs): egress forwarder · `lib/src/icmp_forwarder.rs`
- [SOCKS5 forwarding](https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/socks5_forwarder.rs): alternate egress · `lib/src/socks5_forwarder.rs`
- [HTTP downstream](https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/reverse_proxy.rs): HTTP egress · Supports reverse-proxy and HTTP-oriented endpoint behavior. · `lib/src/reverse_proxy.rs`

### Provisioning and operations

- [Deep-link codec](https://github.com/trusttunnel/trusttunnel/blob/master/deeplink/src/encode.rs): tt:// codec · Encodes and decodes compact client links and certificates. · `deeplink/src/encode.rs`
- [Setup wizard](https://github.com/trusttunnel/trusttunnel/blob/master/tools/setup_wizard/main.rs): interactive provisioning · Composes endpoint files and manages certificate setup. · `tools/setup_wizard/main.rs`
- **Let's Encrypt**: external certificate service
- [Metrics](https://github.com/trusttunnel/trusttunnel/blob/master/lib/src/metrics.rs): observability · `lib/src/metrics.rs`

## Connections

- Endpoint executable → Settings and client config: loads
- Endpoint executable → Server core: starts
- Server core → TLS listener: accepts inbound traffic
- Server core → Capacity and shutdown: governed by
- TLS listener → TLS demultiplexer: encrypted connections
- TLS demultiplexer → HTTP demultiplexer: HTTP traffic
- HTTP demultiplexer → HTTP tunnel codecs: HTTP/1-3 tunnels
- HTTP tunnel codecs → Tunnel sessions: decoded streams
- HTTP tunnel codecs → QUIC multiplexer: QUIC transport
- QUIC multiplexer → Tunnel sessions: multiplexed flows
- Tunnel sessions → Admission controls: authenticates
- Admission controls → TCP forwarding: admitted TCP
- Admission controls → UDP forwarding: admitted UDP
- Admission controls → ICMP forwarding: admitted ICMP
- TCP forwarding → SOCKS5 forwarding: optional proxy egress
- HTTP demultiplexer → HTTP downstream: HTTP downstream
- Settings and client config → Admission controls: credentials and rules
- Setup wizard → Settings and client config: writes configuration
- Setup wizard → Let's Encrypt: obtains certificates
- Endpoint executable → Deep-link codec: exports client links
- Server core → Metrics: emits