System Context¶

Introduction and Goals¶

Tunnel Whisperer creates resilient, application-layer bridges for specific ports across separated private networks. It encapsulates traffic in standard HTTPS to traverse strict firewalls, NAT, and DPI-controlled environments.

Requirements Overview¶

The system connects servers behind private networks to clients behind other private networks, via a publicly reachable relay. All connectivity is egress-only from both sides. The relay is provisioned and owned by an admin machine running in the relay role (tw relay create — an interactive CLI wizard, cloud/Terraform or manual install script). The relay is multi-tenant: additional servers join it through a zero-file, spoken invite (tw relay invite mints a one-time code; tw join redeems it, running a SPAKE2 exchange confirmed by a short authentication string read back between the two humans), each tenant isolated behind its own URL path, CA, and loopback port. Every installation's role (relay, server, or client) is recorded in config and ed25519-signed as tamper-evidence (internal/ops/modeauth).

Quality Goals¶

System Scope and Context¶

Business Context¶

graph LR
    subgraph Server Network
        S[Server - tw server start]
    end

    subgraph Public Cloud
        R[Relay VM]
        C_[Caddy :443 mTLS gate]
        X["Xray (per-tenant VLESS inbounds<br/>on 127.0.0.1)"]
    end

    subgraph Client Network
        CL[Client - tw client connect]
    end

    S -- "mTLS :443 (VLESS+XHTTP, /tw/&lt;id&gt;)" --> C_
    CL -- "mTLS :443 (VLESS+XHTTP, /tw/&lt;id&gt;)" --> C_
    C_ -- "per-tenant handle /tw/&lt;id&gt;" --> X
    X -- "freedom outbound (loopback only)" --> R

Technical Context¶