kulikov0/whitelist-bypass

1. Overall shape

This repo is a multi-platform “tunnel over video call” system. The architectural center is a shared Go transport stack in relay/, while the endpoints are split into creator-side apps and joiner-side apps for Android, iOS, desktop, and headless Linux use.

2. Core data path

The important end-to-end flow is:

system traffic on the joiner device → local tunnel/proxy layer → Go SOCKS5 proxy → Pion-based tunnel session → platform SFU (VK / Telemost / WB Stream) → matching creator-side session → outbound Internet via the creator machine.

The tunnel payload can ride either DataChannel traffic or encoded VP8 video frames, depending on mode and platform constraints.

3. Shared transport/runtime boundary: relay/

relay/ is the shared low-level engine. It contains:

• SOCKS5 proxying and client plumbing

• tunnel protocol framing and multiplexing

• obfuscation

• platform-specific tunnel bridges

• Go mobile bindings for Android/iOS

This is the main boundary where “local network proxy semantics” turn into “traffic embedded in a call.”

4. Tunnel modes

There are two transport modes in the repo:

• DC mode: data goes over SCTP DataChannels.

• Video mode: data is encoded into VP8 video streams.

Both modes share the same higher-level tunnel framing and multiplexing; the difference is only the carrier over the SFU. Video mode is especially important for platforms that throttle or restrict DataChannels.

5. Creator-side implementations

The creator side is split into two architectural paths:

• Legacy browser path: creator-app/ Electron UI plus injected JS hooks in hooks/

• Headless path: pure Go binaries under headless/

The headless path is the preferred architecture in the README because it talks directly to the platform APIs and Pion, avoiding browser automation.

6. Creator app: Electron orchestration

creator-app/ is a desktop control plane. It provides the UI for selecting platform and tunnel mode, and can either:

• run the legacy browser flow with tab management and JS hooks, or

• spawn the headless Go binaries and supervise them

It also handles packaging of hooks, binary discovery, and user-facing link generation/sharing.

7. Headless creator family

The headless binaries are separated by platform:

• headless/vk/

• headless/telemost/

• headless/wbstream/

These create or join calls through platform-specific APIs and then attach the tunnel session directly. Supporting companions exist for joining:

• headless/telemost-joiner/

• headless/wbstream-joiner/

There is also headless/vk-bot/, a VK Long Poll bot that triggers headless creators server-side and returns join links.

8. Joiner-side Android architecture

android-app/ is the primary censored-network client. Its stack is:

• VpnService capture of all device traffic

• tun2socks-style conversion from IP packets to SOCKS5

• local Go proxy/tunnel service

• headless Pion session joined into the call

This app also includes a legacy WebView-based fallback for VK browser hooks, but that path is secondary.

9. Joiner-side iOS architecture

ios-proxy-app/ is narrower in scope than Android: it exposes a local SOCKS5 proxy backed by the shared Go mobile framework (Mobile.xcframework). It does not implement a full system VPN in this repo; instead, the device or an app can be pointed at the SOCKS endpoint.

10. Legacy browser automation layer

The browser-based flow is supported by JS hooks in hooks/ and mirrored assets in android-app/app/src/main/assets/. These scripts patch the calling pages for:

• autoplay / audio muting

• call joining

• video handling

• platform-specific DOM interactions

This layer only matters for the older browser-based VK/Telemost path and is explicitly not used by the headless Go path.

11. Platform-specific signaling and call logic

Inside relay/ and headless/, each platform has its own signaling/call layer:

• VK-specific signaling, cookies, peer/call handling

• Telemost API and tunnel relay integration

• WB Stream session logic and LiveKit-backed mechanics

So the architecture is not a single generic signaling backend; it is a set of per-platform adapters feeding the same tunnel core.

12. Support infrastructure and build/runtime boundaries

The repo includes build and release automation for multiple targets:

• Android, iOS, desktop Electron apps, headless Linux binaries, and Docker builds

• Go + Node.js + Android SDK/NDK + Xcode/macOS as needed per target

The .github workflow and scripts mainly orchestrate packaging; they do not change the runtime architecture, but they reflect that this is a polyglot, multi-artifact system.

13. Observability and operational control

The Android app has a dedicated logs UI, status indicators, and tunnel/service state tracking. The Go side also exposes status/logging concepts used by desktop and headless tooling. In an architecture diagram, this is worth showing as a side-channel from tunnel services to UI/log viewers, not part of the data plane.

14. Test and validation boundary

headless/tests/ contains end-to-end smoke tests for the platform-specific headless flows. These validate that creator/joiner signaling and tunnel establishment work against real platforms, which is important because much of the system depends on external call services.

15. External dependencies that matter architecturally

The system depends on:

• platform call/SFU services: VK Call, Yandex Telemost, WB Stream

• Pion WebRTC in the Go implementation

• Android VpnService / tun2socks behavior

• Electron and WebView for legacy browser automation

• Go mobile bindings for iOS/Android integration

These are the major boundaries where this repo crosses into platform APIs or external infrastructure.