@torrent-tv/proxy 2.89.0 → 2.89.2

package/docs/socks5-egress-research.md

@@ -1,114 +1,114 @@
-# SOCKS5 torrent egress — feasibility research (NOT implemented)
-
-Research only (2026-07-10), no code. Question: can the proxy route its
-**torrent** traffic (peers, trackers, DHT) through an owner-configured SOCKS5
-endpoint (e.g. a VPN provider's) to hide the owner's home IP from the swarm,
-while WebRTC to the viewer stays direct? Roadmap item 8 in the root
-`CLAUDE.md`.
-
-Stack: WebTorrent 2.8.5, Node. Verified against
-`node_modules/webtorrent/lib/*.js` and `index.js`.
-
-## What "torrent traffic" actually is (and which parts can be SOCKS5'd)
-
-SOCKS5 forwards a connection through a relay so the destination sees the
-relay's IP, not ours. It supports TCP (CONNECT) and, in theory, UDP (UDP
-ASSOCIATE) — but UDP-ASSOCIATE is rarely usable from Node libraries that bind
-their own UDP sockets. So per traffic type:
-
-| Traffic | Transport | Where in WebTorrent | SOCKS5? |
-|---|---|---|---|
-| Peer wire (outgoing) | TCP | `torrent.js` `net.connect(opts)` (~L2112) | **Yes** (TCP CONNECT) |
-| Peer wire (outgoing) | µTP (UDP) | `torrent.js` `utp.connect()` (~L2110) | No (UDP, own socket) → **disable** |
-| HTTP/HTTPS trackers | TCP | `bittorrent-tracker` (HTTP agent) | **Yes** (agent) |
-| WSS trackers | TCP (WebSocket) | `bittorrent-tracker` (ws agent) | **Yes** (agent) |
-| UDP trackers (`udp://`) | UDP | `bittorrent-tracker` | No → **drop** (filter announce list) |
-| DHT | UDP | `bittorrent-dht` | No → **disable** (`dht:false`) |
-| LSD (local peer discovery) | UDP multicast | conn-pool | LAN-only leak → **disable** (`lsd:false`) |
-| Incoming peers | TCP/µTP listener | conn-pool | N/A (inbound; see note) |
-
-Conclusion: a clean, leak-free config is **TCP-only through the SOCKS5 relay**
-with every UDP path turned OFF. This is the standard "torrent proxy" model and
-its standard caveat: you lose µTP peers, UDP trackers, and DHT peer discovery —
-peer counts drop, but HTTP/WSS-tracker swarms (like the rutracker trackers our
-test torrents use) still work, and TCP peers are plentiful.
-
-WebTorrent already exposes the needed off-switches (verified in `index.js`):
-`utp: false` (L82), `dht: false` (L127), `lsd: false` (L76), `webSeeds`
-(L161). Announce-list filtering to `http(s)://`/`wss://` is ours to do.
-
-## The hard part: no dialer hook for TCP peers
-
-WebTorrent has **no public option** to supply a custom socket/dialer for
-outgoing peer connections — it calls `net.connect(opts)` directly inside
-`torrent.js`. Three ways around it:
-
-### Approach A — userland, scoped monkeypatch of `net.connect` (+ disable UDP)
-Wrap `net.connect` so that for a **peer destination** it returns a socket
-tunneled through SOCKS5 (via the already-present `socks` package —
-`SocksClient.createConnection({ proxy, command:'connect', destination })`),
-and for everything else (our loopback HTTP server, the signalling tunnel,
-ffmpeg's `127.0.0.1` fetch, DNS) it calls the real `net.connect`.
-- The `socks` dep is ALREADY in `node_modules` (currently transitive) — would
-  become a direct dependency.
-- Shim detail: `net.connect` returns a socket synchronously and connects
-  async; `SocksClient.createConnection` is Promise-based. Need a small adapter
-  that returns a `net.Socket`-like duplex immediately and attaches the real
-  tunneled socket once the SOCKS handshake resolves (or emits `error`). The
-  `socks` package's event API supports this.
-- Scoping rule: SOCKS only for non-local IPv4/IPv6 destinations; NEVER for
-  `127.0.0.1`/`::1`/the tunnel host — otherwise we'd route our own control
-  plane through the VPN.
-- Trackers/webseeds (HTTP/WSS): pass a `socks-proxy-agent` as the HTTP/ws
-  agent to `bittorrent-tracker` / webseed fetches (need to confirm WebTorrent
-  threads an `agent` option through; may need a small patch).
-- Pros: no fork, no build-chain changes, deployment-agnostic. Cons: global
-  monkeypatch is delicate; must be airtight on the scoping rule.
-
-### Approach B — patch/fork WebTorrent to add a `createConnection` hook
-Add an option so `torrent.js` uses `opts.createConnection ?? net.connect`.
-Cleaner and explicit, but a fork to maintain (or an upstream PR — issue
-webtorrent#807 "SOCKS Proxy Support" is open and unresolved, so upstream is
-unlikely soon). More correct long-term if A proves too fragile.
-
-### Approach C — network-level (VPN container / namespace), NOT in-proxy
-Run the whole proxy process behind a VPN with a kill-switch (e.g. a `gluetun`
-sidecar container, or a Linux network namespace bound to the VPN). Catches
-ALL traffic — TCP, µTP, DHT, UDP trackers — leak-proof, zero proxy code.
-Trade-off: not per-app (the whole proxy egresses via VPN, including the
-signalling tunnel unless split), heavier ops, and awkward for the HA addon
-(`host_network: true`). This is the ROBUST alternative to document alongside;
-for a bare-Docker/npm operator it may actually be the better answer than
-in-proxy SOCKS5.
-
-## Kill-switch (fail-closed) — mandatory for the feature to mean anything
-If the SOCKS5 relay is down, torrent traffic must NOT silently fall back to a
-direct connection (that leaks the exact IP we set out to hide). With Approach
-A this is natural: a failed SOCKS handshake fails the peer connection with no
-direct retry, AND all UDP paths are already disabled, so nothing bypasses the
-relay. Must add a startup connectivity self-test + a clear log line
-(BitPlay's "test proxy" pattern), and surface "proxy down → torrent paused"
-rather than leaking.
-
-## Recommended direction (when we build it)
-1. Primary: **Approach A** — `socks` for TCP peers via a scoped `net.connect`
-   shim + `socks-proxy-agent` for HTTP/WSS trackers + webseeds, with
-   `utp:false`, `dht:false`, `lsd:false`, and announce-list filtered to
-   TCP-based trackers. Fail-closed by construction.
-2. Document **Approach C** (VPN container) in the addon/deployment docs as the
-   leak-proof alternative for operators who prefer it.
-3. Approach B only if A's monkeypatch proves too fragile in practice.
-
-## Open questions to resolve at build time (not now)
-- Does WebTorrent 2.8.x thread an `agent`/proxy option to `bittorrent-tracker`
-  and webseed fetches, or is a small patch needed there too?
-- `socks` socket-shim: cleanest way to present a pre-connect `net.Socket`
-  (custom Duplex vs a paused real socket) without confusing
-  `bittorrent-protocol`'s wire setup.
-- Incoming peers: with UDP off and outbound via SOCKS, do we still accept
-  inbound TCP peers directly (that inbound listener exposes the home IP to
-  connecting peers)? For full hiding, inbound may need to be disabled too
-  (accept that peer discovery becomes outbound-only) — decide per privacy goal.
-- Interaction with the UPnP port mapping / WebRTC UDP port (those are for the
-  viewer transport, NOT torrent egress — must stay direct; confirm the shim's
-  scoping never touches them).
+# SOCKS5 torrent egress — feasibility research (NOT implemented)
+
+Research only (2026-07-10), no code. Question: can the proxy route its
+**torrent** traffic (peers, trackers, DHT) through an owner-configured SOCKS5
+endpoint (e.g. a VPN provider's) to hide the owner's home IP from the swarm,
+while WebRTC to the viewer stays direct? Roadmap item 8 in the root
+`CLAUDE.md`.
+
+Stack: WebTorrent 2.8.5, Node. Verified against
+`node_modules/webtorrent/lib/*.js` and `index.js`.
+
+## What "torrent traffic" actually is (and which parts can be SOCKS5'd)
+
+SOCKS5 forwards a connection through a relay so the destination sees the
+relay's IP, not ours. It supports TCP (CONNECT) and, in theory, UDP (UDP
+ASSOCIATE) — but UDP-ASSOCIATE is rarely usable from Node libraries that bind
+their own UDP sockets. So per traffic type:
+
+| Traffic | Transport | Where in WebTorrent | SOCKS5? |
+|---|---|---|---|
+| Peer wire (outgoing) | TCP | `torrent.js` `net.connect(opts)` (~L2112) | **Yes** (TCP CONNECT) |
+| Peer wire (outgoing) | µTP (UDP) | `torrent.js` `utp.connect()` (~L2110) | No (UDP, own socket) → **disable** |
+| HTTP/HTTPS trackers | TCP | `bittorrent-tracker` (HTTP agent) | **Yes** (agent) |
+| WSS trackers | TCP (WebSocket) | `bittorrent-tracker` (ws agent) | **Yes** (agent) |
+| UDP trackers (`udp://`) | UDP | `bittorrent-tracker` | No → **drop** (filter announce list) |
+| DHT | UDP | `bittorrent-dht` | No → **disable** (`dht:false`) |
+| LSD (local peer discovery) | UDP multicast | conn-pool | LAN-only leak → **disable** (`lsd:false`) |
+| Incoming peers | TCP/µTP listener | conn-pool | N/A (inbound; see note) |
+
+Conclusion: a clean, leak-free config is **TCP-only through the SOCKS5 relay**
+with every UDP path turned OFF. This is the standard "torrent proxy" model and
+its standard caveat: you lose µTP peers, UDP trackers, and DHT peer discovery —
+peer counts drop, but HTTP/WSS-tracker swarms (like the rutracker trackers our
+test torrents use) still work, and TCP peers are plentiful.
+
+WebTorrent already exposes the needed off-switches (verified in `index.js`):
+`utp: false` (L82), `dht: false` (L127), `lsd: false` (L76), `webSeeds`
+(L161). Announce-list filtering to `http(s)://`/`wss://` is ours to do.
+
+## The hard part: no dialer hook for TCP peers
+
+WebTorrent has **no public option** to supply a custom socket/dialer for
+outgoing peer connections — it calls `net.connect(opts)` directly inside
+`torrent.js`. Three ways around it:
+
+### Approach A — userland, scoped monkeypatch of `net.connect` (+ disable UDP)
+Wrap `net.connect` so that for a **peer destination** it returns a socket
+tunneled through SOCKS5 (via the already-present `socks` package —
+`SocksClient.createConnection({ proxy, command:'connect', destination })`),
+and for everything else (our loopback HTTP server, the signalling tunnel,
+ffmpeg's `127.0.0.1` fetch, DNS) it calls the real `net.connect`.
+- The `socks` dep is ALREADY in `node_modules` (currently transitive) — would
+  become a direct dependency.
+- Shim detail: `net.connect` returns a socket synchronously and connects
+  async; `SocksClient.createConnection` is Promise-based. Need a small adapter
+  that returns a `net.Socket`-like duplex immediately and attaches the real
+  tunneled socket once the SOCKS handshake resolves (or emits `error`). The
+  `socks` package's event API supports this.
+- Scoping rule: SOCKS only for non-local IPv4/IPv6 destinations; NEVER for
+  `127.0.0.1`/`::1`/the tunnel host — otherwise we'd route our own control
+  plane through the VPN.
+- Trackers/webseeds (HTTP/WSS): pass a `socks-proxy-agent` as the HTTP/ws
+  agent to `bittorrent-tracker` / webseed fetches (need to confirm WebTorrent
+  threads an `agent` option through; may need a small patch).
+- Pros: no fork, no build-chain changes, deployment-agnostic. Cons: global
+  monkeypatch is delicate; must be airtight on the scoping rule.
+
+### Approach B — patch/fork WebTorrent to add a `createConnection` hook
+Add an option so `torrent.js` uses `opts.createConnection ?? net.connect`.
+Cleaner and explicit, but a fork to maintain (or an upstream PR — issue
+webtorrent#807 "SOCKS Proxy Support" is open and unresolved, so upstream is
+unlikely soon). More correct long-term if A proves too fragile.
+
+### Approach C — network-level (VPN container / namespace), NOT in-proxy
+Run the whole proxy process behind a VPN with a kill-switch (e.g. a `gluetun`
+sidecar container, or a Linux network namespace bound to the VPN). Catches
+ALL traffic — TCP, µTP, DHT, UDP trackers — leak-proof, zero proxy code.
+Trade-off: not per-app (the whole proxy egresses via VPN, including the
+signalling tunnel unless split), heavier ops, and awkward for the HA addon
+(`host_network: true`). This is the ROBUST alternative to document alongside;
+for a bare-Docker/npm operator it may actually be the better answer than
+in-proxy SOCKS5.
+
+## Kill-switch (fail-closed) — mandatory for the feature to mean anything
+If the SOCKS5 relay is down, torrent traffic must NOT silently fall back to a
+direct connection (that leaks the exact IP we set out to hide). With Approach
+A this is natural: a failed SOCKS handshake fails the peer connection with no
+direct retry, AND all UDP paths are already disabled, so nothing bypasses the
+relay. Must add a startup connectivity self-test + a clear log line
+(BitPlay's "test proxy" pattern), and surface "proxy down → torrent paused"
+rather than leaking.
+
+## Recommended direction (when we build it)
+1. Primary: **Approach A** — `socks` for TCP peers via a scoped `net.connect`
+   shim + `socks-proxy-agent` for HTTP/WSS trackers + webseeds, with
+   `utp:false`, `dht:false`, `lsd:false`, and announce-list filtered to
+   TCP-based trackers. Fail-closed by construction.
+2. Document **Approach C** (VPN container) in the addon/deployment docs as the
+   leak-proof alternative for operators who prefer it.
+3. Approach B only if A's monkeypatch proves too fragile in practice.
+
+## Open questions to resolve at build time (not now)
+- Does WebTorrent 2.8.x thread an `agent`/proxy option to `bittorrent-tracker`
+  and webseed fetches, or is a small patch needed there too?
+- `socks` socket-shim: cleanest way to present a pre-connect `net.Socket`
+  (custom Duplex vs a paused real socket) without confusing
+  `bittorrent-protocol`'s wire setup.
+- Incoming peers: with UDP off and outbound via SOCKS, do we still accept
+  inbound TCP peers directly (that inbound listener exposes the home IP to
+  connecting peers)? For full hiding, inbound may need to be disabled too
+  (accept that peer discovery becomes outbound-only) — decide per privacy goal.
+- Interaction with the UPnP port mapping / WebRTC UDP port (those are for the
+  viewer transport, NOT torrent egress — must stay direct; confirm the shim's
+  scoping never touches them).