TeroVPN

High-Throughput, Low-Latency Virtual Private Network Client
Cross-platform architecture engineered for Windows, macOS, Linux, and Android.
Powered by WireGuard MASQUE (RFC 9298 HTTP/3 QUIC) encapsulation across Fastly Anycast edge infrastructure.

---

Overview

TeroVPN is a production-grade virtual private network client designed to bypass advanced state-level censorship, protocol throttling, and deep packet inspection (DPI). By encapsulating encrypted WireGuard datagrams into standard HTTP/3 QUIC and HTTP/2 MASQUE tunnels over UDP/TCP port 443, TeroVPN renders VPN traffic indistinguishable from ordinary HTTPS web traffic.

The system delivers native line-speed bandwidth, instant connection migration, multi-account quota rotation, and platform-native integration across all desktop and mobile operating systems.

---

Brand Identity & Official Icons

Light Edition Frosted Lavender Vector Squircle

Dark Liquid Glass Edition Obsidian Refractive Optic Canvas

---

Downloads & Platform Packages

Platform	Target Environment	Package Format	Distribution Architecture	Download
Windows	Windows 10, 11 (64-bit)	Setup EXE Installer Portable ZIP	Inno Setup Native Installer with system proxy auto-routing and TUN driver	Get Windows (.exe) Portable (.zip)
macOS	macOS 11.0+ (Big Sur, Monterey, Ventura, Sonoma, Sequoia)	Apple Disk Image (.dmg) Tarball (.tar.gz)	Universal Drag-and-Drop Disk Image with unsandboxed socket permissions	Get macOS (.dmg) Bundle (.tar.gz)
Linux	Ubuntu, Debian, Fedora, Arch, openSUSE (x86_64)	Standalone AppImage Tarball (.tar.gz)	Single-file self-contained binary adhering to freedesktop.org specifications	Get Linux (.AppImage) Tarball (.tar.gz)
Android	Android 8.0+ (Oreo through Android 15)	Release APK	Android VpnService integration with 120Hz native refresh rate and ProGuard tuning	Get Android (.apk)

---

Step-by-Step Packet Lifecycle & Tunneling Mechanism

End-to-End Tunnel Pipeline

flowchart LR
    A["Client Application<br/>(Browsers / Apps)"] --> B["Virtual TUN / Proxy<br/>(127.0.0.1:10810)"]
    B --> C["WireGuard Core<br/>(ChaCha20-Poly1305)"]
    C --> D["MASQUE Layer<br/>(HTTP/3 QUIC 443)"]
    D --> E["Fastly Anycast Edge<br/>(33 Global PoPs)"]
    E --> F["Target Host<br/>(Clean Egress IP)"]

Detailed Packet Sequence Flow

sequenceDiagram
    autonumber
    actor ClientApp as Application (e.g., Chrome / Terminal)
    participant HostOS as Host OS Network Layer
    participant LocalCore as TeroVPN Core Engine (terovpn-core)
    participant CryptoEngine as WireGuard Cryptographic Engine
    participant MasqueLayer as MASQUE Encapsulator (RFC 9298)
    participant FastlyEdge as Fastly Anycast Edge PoP
    participant RemoteServer as Remote Destination Server

    Note over ClientApp,HostOS: Phase 1: Local Inbound Capture
    ClientApp->>HostOS: Generates TCP/UDP socket request
    HostOS->>LocalCore: Captures and routes packet to 127.0.0.1:10810 (Proxy/TUN)
    
    Note over LocalCore,CryptoEngine: Phase 2: Cryptographic Encryption
    LocalCore->>CryptoEngine: Ingests raw IP datagram
    CryptoEngine->>CryptoEngine: Encrypts packet using ChaCha20-Poly1305 with 1-RTT Noise protocol
    CryptoEngine-->>LocalCore: Outputs authenticated WireGuard ciphertext datagram
    
    Note over LocalCore,MasqueLayer: Phase 3: MASQUE Protocol Encapsulation
    LocalCore->>MasqueLayer: Passes WireGuard datagram to MASQUE capsule builder
    MasqueLayer->>MasqueLayer: Encapsulates into HTTP/3 DATAGRAM frame (RFC 9298 / CONNECT-UDP)
    MasqueLayer->>FastlyEdge: Transmits payload over TLS 1.3 QUIC connection on port 443
    Note over MasqueLayer,FastlyEdge: Deep Packet Inspection (DPI) sees only valid HTTPS traffic to Fastly CDN
    
    Note over FastlyEdge,RemoteServer: Phase 4: Edge Decapsulation & Egress
    FastlyEdge->>FastlyEdge: Terminates QUIC session, validates account token pass, decapsulates WireGuard frame
    FastlyEdge->>RemoteServer: Routes outbound packet via selected Anycast exit IPv4/IPv6 node
    RemoteServer-->>FastlyEdge: Remote host returns application response
    
    Note over FastlyEdge,ClientApp: Phase 5: Reverse Stream Decryption & Delivery
    FastlyEdge-->>MasqueLayer: Encapsulates response into HTTP/3 return stream
    MasqueLayer-->>LocalCore: Receives and extracts WireGuard ciphertext
    LocalCore->>CryptoEngine: Authenticates and decrypts packet
    CryptoEngine-->>HostOS: Delivers original plaintext IP datagram to loopback
    HostOS-->>ClientApp: Application receives verified data stream with zero identity leak

---

Detailed Protocol Matrix

Protocol Specification	Underlying Transport	Port Configuration	DPI / Firewall Bypass	Throughput & Latency	Best Suited Scenario
Smart (Automatic)	Dynamic Selection	Dynamic (443 / 51820)	Maximum Adaptive	Auto-Optimized	Default recommendation for all client sessions
WireGuard (UDP)	QUIC / UDP	Port 443 / 51820	High	Lowest Latency (<20ms)	Low-ping competitive gaming and 4K media streaming
WireGuard (TCP)	TLS / TCP	Port 443	Very High	Low Latency (~25ms)	Firewalled networks where outbound UDP is throttled or dropped
Stealth (TLS Obfuscated)	Obfuscated TLS Stream	Port 443	Maximum Evasion	Moderate Throughput	Restrictive nation-state censorship and deep packet inspection
OpenVPN (UDP)	OpenVPN Datagram	Port 1194 / 51820	High	Low Latency (~30ms)	Legacy infrastructure requiring conventional tunnel standards
OpenVPN (TCP)	OpenVPN Stream	Port 443	High	Moderate Throughput	Strict captive portals and enterprise proxy firewalls
IKEv2	Native IPSec / UDP	Port 500 / 4500	Standard	Very Low Latency	macOS and iOS mobile handoffs across cellular and Wi-Fi

---

Core System Features

Mobile QR Code Handshake (SignInWithPhoneScreen)

Enables cross-device account authentication without typing passwords:

1. Navigate to Settings > Account > Sign in with phone on Windows, macOS, or Linux.
2. An interactive cryptographic pairing token (terovpn://auth?session=...) is generated with a 5-minute countdown.
3. Scanning the code via the TeroVPN mobile app instantly authenticates the desktop instance.

Geographic Telemetry Canvas (ProtonWorldMap)

Real-time geographic visualization rendered on the client dashboard:

• Origin Node: Pinpoints real user location and connection status.
• Geodesic Flight Arc: Projects an animated flight trajectory with a continuous photon energy beam from Origin to Destination.
• Destination Beacons: Tri-concentric expanding ripple waves display destination city metrics, distance in kilometers, and cryptographic cipher status.

Advanced Leak Protection & System Controls

• IPv6 Leak Protection: Null-routes unencrypted IPv6 packets outside the tunnel.
• DNS Leak Protection: Forces all DNS requests through private encrypted resolvers.
• Custom DNS Configurations: Direct support for custom resolvers with built-in presets for Cloudflare, Google, Quad9, and AdGuard.
• LAN Traffic Bypass: Direct routing for local area network devices including printers, smart home peripherals, and NAS storage.
• Alternative Routing: Automatically falls back to secondary CDN relays (Cloudflare, AWS) if primary server endpoints are restricted.
• Moderate NAT: Optimizes peer-to-peer VoIP and multiplayer gaming connections.
• Custom MTU Tuning: Adjusts packet boundaries between 1280 and 1500 bytes to eliminate packet fragmentation on mobile hotspots.

---

Source Compilation

System Prerequisites

• Flutter SDK (v3.13 or newer; v3.47+ recommended)
• Android SDK & Android Studio (API level 26 minimum, API level 34+ target)
• Microsoft Visual Studio 2022 with C++ Desktop Workload (Windows)
• Xcode and Command Line Tools (macOS)
• Clang, CMake, Ninja, and GTK3 development libraries (Linux)

Build Instructions

# 1. Clone repository
git clone https://github.com/smartworldarafath/TeroVPN.git
cd TeroVPN

# 2. Fetch dependencies
cd app
flutter pub get

# 3. Verify static analysis and test suite
flutter analyze
flutter test

# 4. Target compilation:
flutter build windows --release    # Windows executable
flutter build macos --release      # macOS application bundle
flutter build linux --release      # Linux GTK bundle
flutter build apk --release        # Android package

---

Repository Layout

TeroVPN/
├── app/
│   ├── android/              # Android VpnService bindings and ProGuard rules
│   ├── assets/               # Country flags, vector assets, and typography
│   ├── ios/                  # iOS Xcode project configuration
│   ├── lib/
│   │   ├── core/             # Process controllers, API endpoints, and preference storage
│   │   ├── theme/            # Theme manager and Liquid Glass styling
│   │   └── ui/
│   │       ├── components/   # Reusable widgets, flag renders, and dialogs
│   │       ├── countries/    # Server selection and latency telemetry
│   │       ├── desktop/      # Dedicated desktop sidebar and responsive views
│   │       ├── home/         # Dashboard, ProtonWorldMap, and status cards
│   │       ├── profiles/     # Fast presets and Multi-Account Token Pool
│   │       ├── settings/     # Account, phone QR sign-in, and advanced functions
│   │       └── shell/        # Navigation shell and animated switcher
│   ├── linux/                # Native Linux GTK runner
│   ├── macos/                # Native macOS runner and unsandboxed entitlements
│   ├── pubspec.yaml          # Flutter package definitions
│   ├── test/                 # Automated unit and widget tests
│   └── windows/              # Windows C++ runner and CMake configuration
├── docs/
│   ├── branding/             # Official app icons and brand assets
│   │   └── platforms/        # Official operating system platform marks
│   └── screenshots/          # Application interface captures
├── linux/
│   └── appimage/             # AppRun and desktop entry for AppImage builds
├── windows/
│   └── installer/            # Inno Setup Windows installer configuration
├── .github/
│   └── workflows/            # GitHub Actions CI matrix (Windows, macOS, Linux)
└── README.md                 # Technical documentation

---

Security & Verification Standards

• Zero Plaintext Credentials: All session tokens and authentication parameters are stored in secured platform keystores.
• Complete DNS & IP Containment: Mandatory loopback binding and system proxy integration ensure complete elimination of WebRTC, DNS, and IPv6 leaks.
• Zero-Logs Guarantee: TeroVPN operates under a strict zero-knowledge model. No browsing activity, DNS queries, or session connection logs are ever recorded.

---

License

This software is released under the GNU General Public License v3.0 (GPL-3.0). Refer to the LICENSE file for complete licensing terms.