feat: Add SOCKS5 Proxy Support with Bootstrap Only Mode by scrense-hash · Pull Request #1752 · session-foundation/session-desktop

scrense-hash · 2026-01-03T18:54:42Z

Summary

This change adds SOCKS5 proxy support to Session Desktop, including a Bootstrap-only mode (proxy only for seed-node bootstrap traffic) and auto-updater proxy support for environments where direct Internet access is blocked.

The implementation supports both per-request SOCKS routing for node-fetch traffic and (optionally) global Electron proxying for the full application, with immediate application from the Settings UI.

User-Facing Features

1) SOCKS5 proxy (optional authentication)

Route network requests through a SOCKS5 proxy.
Supports both unauthenticated proxies and username/password authentication.
Uses socks5h://… for DNS-through-proxy semantics when using the per-request agent.
Preserves TLS options when tunneling through SOCKS (certificate pinning remains effective).

2) Bootstrap-only mode

When Bootstrap-only is enabled:

Only seed-node bootstrap / discovery traffic is routed through SOCKS (FetchDestination.SEED_NODE).
Other destinations (service nodes, Session server, SOGS, etc.) remain direct for better performance once connected.
Global Electron proxy is intentionally not configured in this mode (proxying is done per-request where applicable).

3) Proxy settings UI + immediate apply

New Settings → Proxy page.
Enable/disable toggle.
Bootstrap-only toggle.
Host/port fields + optional username/password.
Input validation and toast-based error/success feedback.
Settings persist to storage and apply immediately via IPC (apply-proxy-settings).

4) Auto-updater via proxy

Auto-update checks and downloads can run through the configured SOCKS5 proxy.
To avoid global proxy side effects, the updater can use a dedicated Electron session:
- If bootstrap-only is enabled, the updater uses session.fromPartition('persist:auto-updater').
- Otherwise, it uses session.defaultSession.
Updated to work with electron-updater where netSession is read-only by setting the backing _netSession field.

Technical Notes (Implementation Details)

Request-level proxying for Session network fetches

ts/session/utils/InsecureNodeFetch.ts
- Introduces SocksProxyAgentWithTls (extends socks-proxy-agent) to preserve TLS options for secure endpoints.
- Agent caching keyed by proxy URL + TLS options to avoid re-creating agents for every request.
- Destination-based routing:
  - Full proxy mode ⇒ proxy for all destinations.
  - Bootstrap-only ⇒ proxy only for FetchDestination.SEED_NODE.
- SOCKS agent timeout increased to 30s to account for handshake + routing.

Seed-node bootstrap integration

ts/session/apis/seed_node_api/SeedNodeAPI.ts
- Marks seed-node calls as FetchDestination.SEED_NODE.
- Increases request timeout when proxy is enabled (30s vs 5s).

Global Electron proxy integration (full proxy mode)

ts/mains/main_node.ts
- Applies session.defaultSession.setProxy({ proxyRules: 'socks5://host:port' }) when proxy is enabled and not bootstrap-only.
- Sets HTTP_PROXY / HTTPS_PROXY / NO_PROXY env vars for components that rely on standard proxy env vars.
- Handles proxy authentication via Electron app.on('login', …) when authInfo.isProxy.

Auto-updater integration

ts/updater/updater.ts
- Configures proxy on the chosen Electron session (default or persist:auto-updater).
- Assigns the session to the updater via _netSession to avoid runtime errors with read-only netSession.

Security / Behavior Considerations

Bootstrap-only mode is explicitly designed to avoid routing all traffic through a proxy: only initial seed bootstrap is proxied.
In full-proxy mode, global Electron proxying is enabled; ensure users understand that this affects Electron-level networking.
Local bypass rules are set to '<local>' to avoid proxying local traffic.

Test Builds

Fork release (recommended download link)

https://github.com/scrense-hash/session-desktop/releases/tag/v1.17.6-socks5-proxy

Testing

Tested scenarios:

✅ Tor SOCKS5 proxy (localhost:9050)
✅ Authenticated SOCKS5 proxies (username/password)
✅ Unauthenticated SOCKS5 proxies
✅ Bootstrap-only mode (SEED_NODE via proxy; other destinations direct)
✅ Full proxy mode (global Electron proxy enabled; app traffic routed via SOCKS)
✅ TLS/certificate pinning preserved when tunneling through SOCKS (SocksProxyAgentWithTls)
✅ Auto-updater works via proxy (no netSession TypeError; uses dedicated session when bootstrap-only)

… state

Add "Bootstrap Only" toggle in proxy settings to use proxy only for initial connection phase (handshake). When enabled, only SEED_NODE requests go through proxy, all other traffic is direct. Changes: - Add proxyBootstrapOnly setting key - Add UI toggle in ProxySettingsPage - Implement shouldUseProxyForDestination() logic - Add localization for ru and en - Update getProxyAgent() to accept destination parameter 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Resolved conflicts: - _locales/en/messages.json and _locales/ru/messages.json were deleted in upstream (migrated to new localization system) - Added SOCKS5 proxy translations to new localization system (ts/localization/generated/english.ts and translations.ts) - Updated package.json with SOCKS5 dependencies (smart-buffer, socks, socks-proxy-agent) - Updated yarn.lock from upstream New localization system includes all proxy-related strings: - proxyEnabled, proxyHost, proxyPort - proxyAuthUsername, proxyAuthPassword - proxyBootstrapOnly, proxyBootstrapOnlyDescription - proxySettings, proxySaved, proxyValidationError All SOCKS5 proxy functionality maintained with Bootstrap Only mode. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

This file was auto-generated by the localization code generator. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Added sessionProxy and all related proxy tokens to generated localization files: - sessionProxy, proxyEnabled, proxyDescription - proxyBootstrapOnly, proxyBootstrapOnlyDescription - proxyHost, proxyPort, proxyAuthUsername, proxyAuthPassword - proxySaved, proxyValidationError tokens This fixes the missing "Proxy" menu item in Settings UI. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Added all proxy-related translations to Russian locale: - sessionProxy, proxyEnabled, proxyDescription - proxyBootstrapOnly, proxyBootstrapOnlyDescription - proxyHost, proxyPort, proxyAuthUsername, proxyAuthPassword - proxySaved, proxyValidationError and all related tokens This completes the proxy UI localization. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

SOCKS_PROXY_PATCH.md

package.json

ts/components/dialog/user-settings/pages/ProxySettingsPage.tsx

ts/data/settings-key.ts

ts/session/onions/onionPath.ts

ts/session/utils/InsecureNodeFetch.ts

ts/updater/updater.ts

package.json

ts/session/utils/InsecureNodeFetch.ts

…oves unnecessary async toggles, and simplifies the initial useEffect per Bilb’s suggestion; proxyType removed from settings-key.ts. Proxy plumbing: insecureNodeFetch now builds a final agent from caller-provided TLS options (call sites pass explicit TLS opts for seed-node and snode agents) and keeps detailed errors at debug with a short error message. Seed/onion/session RPC calls supply TLS options explicitly to avoid introspection. Proxy metadata file SOCKS_PROXY_PATCH.md removed. Proxy + updater: main process applyProxySettings sets proxy env vars (with auth) and default session proxy, clears them when disabled/bootstrap-only, and keeps credentials out of logs. Auto-updater uses session.defaultSession and no longer short-circuits when proxy is on, so updates can flow via the proxy.

…po, and regenerated yarn.lock based on the current package.json. Ran yarn lint (Prettier adjusted the formatting in InsecureNodeFetch.ts; I reverted the formatting for locales.ts).

scrense-hash · 2026-01-12T20:50:32Z

Further testing is required, DPI with bootstrap only enabled behaves inconsistently.

WARN 2026-01-12T19:37:30.975Z requestSnodesForPubkeyWithTargetNode attempt #3 failed. 1 retries left...
ERROR 2026-01-12T19:37:41.402Z insecureNodeFetch error: network timeout at: [REDACTED]
WARN 2026-01-12T19:37:41.402Z sendOnionRequestNoRetries error message: network timeout at: [REDACTED]
WARN 2026-01-12T19:37:41.403Z processOnionRequestErrorOnPath httpStatusCode: 8888 ciphertext:
WARN 2026-01-12T19:37:41.403Z [path] Got status: 8888
INFO 2026-01-12T19:37:41.403Z [onionPaths] incrementBadPathCountOrDrop starting with guard (...e86c5a), reason: "processAnyOtherErrorOnPath: Otherwise we increment the whole path failure count"
INFO 2026-01-12T19:37:41.403Z [onionPaths] handling bad path for path index1, reason: "processAnyOtherErrorOnPath: Otherwise we increment the whole path failure count"
WARN 2026-01-12T19:37:41.403Z Failure threshold reached for snode: (...7edde6); dropping it.
WARN 2026-01-12T19:37:41.405Z [snodePool] Dropping (...7edde6) from snode pool for reason: "Failure threshold reached for snode: (...7edde6); dropping it. (processAnyOtherErrorOnPath: Otherwise we increment the whole path failure count)". 1471 snodes remaining in randomPool
INFO 2026-01-12T19:37:41.426Z [onionPaths] dropping snode (...7edde6) from path index: 1 with reason: "Failure threshold reached for snode: (...7edde6); dropping it. (processAnyOtherErrorOnPath: Otherwise we increment the whole path failure count)"
WARN 2026-01-12T19:37:41.449Z Failure threshold reached for snode: (...2e815d); dropping it.
WARN 2026-01-12T19:37:41.449Z [snodePool] Dropping (...2e815d) from snode pool for reason: "Failure threshold reached for snode: (...2e815d); dropping it. (processAnyOtherErrorOnPath: Otherwise we increment the whole path failure count)". 1470 snodes remaining in randomPool
INFO 2026-01-12T19:37:41.454Z [onionPaths] dropping snode (...2e815d) from path index: 1 with reason: "Failure threshold reached for snode: (...2e815d); dropping it. (processAnyOtherErrorOnPath: Otherwise we increment the whole path failure count)"
WARN 2026-01-12T19:37:41.460Z [snodePool] Dropping (...e86c5a) from snode pool for reason: "processAnyOtherErrorOnPath: Otherwise we increment the whole path failure count". 1469 snodes remaining in randomPool
INFO 2026-01-12T19:37:41.465Z [onionPaths] Dropping path starting with guard node (...e86c5a); index:1 with reason: "processAnyOtherErrorOnPath: Otherwise we increment the whole path failure count"
INFO 2026-01-12T19:37:41.467Z [onionPaths] buildNewOnionPaths - building new onion paths...

scrense-hash

All requested changes addressed

scrense-hash and others added 15 commits January 3, 2026 21:53

feat: add SOCKS proxy support

71e1612

Fix proxy agent TLS caching

7d35afd

Fix TLS options flag in proxy agent

27c0267

fix: show Save button when proxy is disabled to allow saving disabled…

9187eca

… state

fix: add proxy-bootstrap-only to SettingsToggles type

896c90b

chore: add generated locales.ts file

e3c90e6

This file was auto-generated by the localization code generator. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

chore: update proxy settings and localization files

1a0984e

CI: fallback when yarn.lock is stale

9cd92f1

Fix TS build errors (Flex padding, CrowdinLocale wrapper)

bdf18be

Lint: remove console.error from proxy apply error path

f7cdc43

CI: make dedup step non-blocking on forks

fbb63e2

scrense-hash force-pushed the feature/socks5-proxy-for-pr branch 2 times, most recently from 9300e8d to fbb63e2 Compare January 9, 2026 16:41

ci: trigger clean build without cache

a789110

scrense-hash closed this Jan 9, 2026

scrense-hash reopened this Jan 9, 2026

Bilb requested changes Jan 12, 2026

View reviewed changes

scrense-hash added 9 commits January 12, 2026 16:55

Updated the dependencies: ran yarn install --ignore-scripts in the re…

f0c0a85

…po, and regenerated yarn.lock based on the current package.json. Ran yarn lint (Prettier adjusted the formatting in InsecureNodeFetch.ts; I reverted the formatting for locales.ts).

Fix proxy build errors

dc8d5cb

Fix updater lint error (remove unused session import)

17e54a4

Route auto-updater through proxy

4272d13

Fix proxy config for updater

ef19932

Docs: update SOCKS5 proxy PR description

4e6432c

Docs: refresh SOCKS5 proxy PR description

91b50c0

Refactor proxy settings + reduce log noise

d7a8b70

scrense-hash added 3 commits January 12, 2026 21:52

Refactor proxy agent construction

2e4ba72

Fix proxy agent typing and toggle handlers

72600dc

fix: guard checkServerIdentity when building TLS cache key

62b0eb7

scrense-hash commented Jan 23, 2026

View reviewed changes

KeeJef mentioned this pull request Jan 26, 2026

Proxy Support #816

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Add SOCKS5 Proxy Support with Bootstrap Only Mode#1752

feat: Add SOCKS5 Proxy Support with Bootstrap Only Mode#1752
scrense-hash wants to merge 28 commits intosession-foundation:devfrom
scrense-hash:feature/socks5-proxy-for-pr

scrense-hash commented Jan 3, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

scrense-hash commented Jan 12, 2026 •

edited

Loading

Uh oh!

scrense-hash left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

scrense-hash commented Jan 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

User-Facing Features

1) SOCKS5 proxy (optional authentication)

2) Bootstrap-only mode

3) Proxy settings UI + immediate apply

4) Auto-updater via proxy

Technical Notes (Implementation Details)

Request-level proxying for Session network fetches

Seed-node bootstrap integration

Global Electron proxy integration (full proxy mode)

Auto-updater integration

Security / Behavior Considerations

Test Builds

Fork release (recommended download link)

Testing

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

scrense-hash commented Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

scrense-hash left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

scrense-hash commented Jan 3, 2026 •

edited

Loading

scrense-hash commented Jan 12, 2026 •

edited

Loading