How Telegram’s new WEB Proxy works: technical details

More details have emerged about Telegram Desktop’s new WEB Proxy transport, which was previously spotted in the client’s code.

A technical analysis of the implementation shows that Telegram has built a working prototype and released the server-side component, called tproxy-server, which is currently available as a proof of concept.

The new system does not replace MTProxy or change how its encryption works. The client still establishes a standard MTProxy connection, but the already encrypted traffic is then wrapped inside a web transport through WebView. The web layer only handles data delivery between the client and the intermediary server.

How WEB Proxy transports traffic

• To send multiple Telegram connections through a single web connection, developers added a lightweight multiplexing protocol with its own set of control frames. OPEN starts a connection, DATA carries payload data, WINDOW manages how much data the receiver can accept, and CLOSE terminates the stream. PING and PONGare used to keep the connection alive, while HELLO and WELCOME establish the session. Each logical stream has its own state, while all streams share the same channel.
• The system supports four delivery modes, selected by the server rather than the user.
• The first mode uses sequential HTTPS requests. The second uses HTTPS with a separate channel for each logical connection. The third and fourth rely on WebSocket, either with all streams sharing one connection or with each stream using its own connection.
• All modes use the standard HTTPS port 443, making the traffic appear similar to regular web activity. On the server side, the shared stream is handled by tproxy-server, which splits it back into individual connections and forwards them to a locally running official MTProxy instance.

The DATA frames remain opaque to tproxy-server. The relay cannot decrypt MTProxy traffic, and the client cannot use the relay to connect to arbitrary external addresses. In other words, a WEB Proxy operator cannot read messages or turn the system into an open proxy.

How WEB Proxy disguises itself as a regular website

The key part of the design is how the connection appears from the outside.

The client only needs a domain name and a standard MTProxy secret. Telegram generates a special parameter on the device that is required to open the so-called bridge page.

The secret itself is never passed to JavaScript. After the page loads, the temporary parameter is removed from the URL, and the server issues a temporary 256-bit token used to authenticate the session.

If someone opens the same URL without the correct parameter, the server simply returns a normal homepage.

A domain owner can host a regular website, APIs and other services on the same domain. The bridge page is only shown to users with the correct domain-and-secret combination.

What WEB Proxy allows inside WebView

The bridge page inside WebView is intentionally restricted to reduce the attack surface. It cannot access:

• cookies;
• browser local storage;
• IndexedDB and Service Workers;
• file uploads, pop-ups, forms, external resources, or device permissions such as the camera, microphone and clipboard.

It only keeps the minimum functionality required:

• an embedded script;
• an HTTPS/WebSocket connection to the same domain;
• a dedicated interface for communicating with Telegram Desktop.

This significantly reduces the potential attack surface from a malicious proxy server.

When WEB Proxy may become available

The desktop client already contains a hidden WebView-based transport operating at the process level, along with a fallback option using the system browser. Telegram is also preparing implementations for Android (Android System WebView) and iOS (WKWebView).

Future settings already reserve the links t.me/webproxy and tg://webproxy, but the t.me website does not currently handle the /webproxy route. That means there is still no one-click setup option available for regular users.

Telegram has not announced when WEB Proxy will arrive in the stable version of Telegram Desktop.