Native proxy settings

[tim2zg]

Description

This PR implements a native "Network Proxy" settings window, allowing users to configure their proxy connection directly within the application UI instead of relying on command-line arguments or environment variables.

Changes

• Added a new Proxy Settings entry to the "View" menu.
• Implemented a dedicated Electron window with a UI that matches the Element look and feel (including dark/light mode support).
• Created a new module to handle applying proxy configurations to the Electron defaultSession.
• Persisted proxy configuration using the existing Store.

Solution for Issue: element-hq/element-web#32407

Checklist

• Ensure your code works with manual testing.
• New or updated public/exported symbols have accurate TSDoc documentation.
• Linter and other CI checks pass.
• I have licensed the changes to Element by completing the Contributor License Agreement (CLA)

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ tim2zg
❌ Copilot
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[dosubot]

Related Documentation

No published documentation to review for changes on this repository.

Write your first living document

^{How did I do? Any feedback?}  

[t3chguy]

Can this be cts instead and be transpiled by typescript into the lib dir instead of avoiding typescript? I.e follow the path of the main preload script

[tim2zg]

Fair, done

[t3chguy]

This is exciting, but a few points

Additionally, looks like the autoUpdater won't respect these proxy settings which is problematic without a warning to the user

[t3chguy]

We are not New Vector anymore, this should be your copyright anyway

[tim2zg]

Done

[t3chguy]

Ditto

[t3chguy]

Ditto

[t3chguy]

I think this will want to use Compound components for UI, so may need more complexity and likely to be within the main UI rather than entirely standalone. Needs design

[tim2zg]

Will need help with this

[t3chguy]

Needs i18n

[tim2zg]

tried it but not sure if it's right

[t3chguy]

I don't think this is true with safeStorage, a single random string is stored in system keychain and other secrets are encrypted symmetrically using it. Additionally the user may have no keychain where this message becauses confusing.

[tim2zg]

Changed it

[t3chguy]

I have licensed the changes to Element by completing the Contributor License Agreement (CLA)

You checked this box but the CLA does not appear to be signed.

Could you also include screenshots of what the UI you added looks like?

[tim2zg]

This is exciting, but a few points

Additionally, looks like the autoUpdater won't respect these proxy settings which is problematic without a warning to the user

Added a notice

[tim2zg]

I have licensed the changes to Element by completing the Contributor License Agreement (CLA)

You checked this box but the CLA does not appear to be signed.

Could you also include screenshots of what the UI you added looks like?

Also, the CLA is not okay because I tried using GitHub Copilot at the beginning and didn’t reset the history. GitHub now lists Copilot as a contributor.

[americanrefugee]

Hello, thanks for your contribution @tim2zg!

In order to integrate this feature into the product, the form you've proposed will need to be presented in a modal (rather than in a separate browser tab). Then there will be 2 places from which the user can access this modal: From the Welcome screen, and from Settings. Here are visuals to help illustrate:

1. On the Sign in page, we would add a text link in the footer

2. Click the link to launch the modal. By default the modal would show just the 3 radio button options with the first selected. The "Save" button is disabled until a change is made.

3. If the last option is selected, then the form appears below. The "Cancel" and "Save" buttons should be sticky and the form scrolls behind until the end. Once the user has entered the minimum information, the "Save" button is enabled.

4. Once signed into the client, the user can go to Settings > Security & Privacy > Network proxy to manage this setting.

Ideally, please provide 1.) the modal and form contents and 2.) the settings section block.

As for UI components, use those provide by our Compound Design System at https://compound.element.io

Here's a quick cheat sheet:

• Primary button
• Secondary button
• Close button
• Form
• Glass edge (for modal)
• Heading text
• Body text

[tim2zg]

Hey, thanks for the feedback. Would this then be added to the main element app repo or injected into it from the wrapper? And would I then need to open up a second pull request there?

Best regards

[t3chguy]

Yes the UI code would live in element-web & communicate over IPC, there's already a wrapper for settings to handle the IPC communication for you. In the future it may be possible to have the UI code live on the element-desktop side and be injected as a module but we aren't there yet. In the near future element-desktop will be re-merged into the element-web (mono)repo to make contributions like this easier.

[fjh1997]

Thanks for working on this! This feature is highly anticipated by many users, including myself, as it significantly improves the desktop experience. Looking forward to seeing this merged. Is there anything the community can help with to speed up the process? @tim2zg

[tim2zg]

Hello @fjh1997,

Thank you. I will open another PR on the web repo shortly. I could use some help testing!

Best regards,
Tim

[fjh1997]

@tim2zg Awesome! Let me know when it's ready for testing.

[dbkr]

I'm just going to put this back into draft while it's still waiting on other parts.

[tim2zg]

UI PR: element-hq/element-web#32804

[tim2zg]

@fjh1997 Please feel free to test:)

[fjh1997]

Hi @tim2zg,

I’m a user in mainland China, so I need a proxy to log in to Matrix at all.

I tested your desktop PR together with the corresponding element-web PR locally. The proxy UI does appear after login, but I still ran into a few usability problems:

1. There is no proxy settings entry on the welcome/login screen.
   Without that, I cannot configure a proxy before login, but without a proxy I also cannot log in in the first place.

2. If the saved proxy becomes invalid, and I log out, I get stuck again.
   At that point I cannot log in, and I also cannot get back to the proxy settings to fix it.

3. If the default/configured homeserver is unreachable from the current network, the app can sit on a blank/white screen for a long time.
   In that state, it would be much better if the user could still change both proxy settings and homeserver settings to recover.

4. A proxy connectivity test button would also be very helpful.
   That would let users quickly confirm whether the configured proxy is actually working.

5. With the original PR combination, I also hit:
   Error
Unable to load! Check your network connectivity and try again.
   especially around the Security & Privacy area.
   I only got past that locally after applying extra patches like these:

diff --git a/packages/shared-components/src/settings/NetworkProxyView/NetworkProxyView.tsx b/packages/shared-components/src/settings/NetworkProxyView/NetworkProxyView.tsx
--- a/packages/shared-components/src/settings/NetworkProxyView/NetworkProxyView.tsx
+++ b/packages/shared-components/src/settings/NetworkProxyView/NetworkProxyView.tsx
@@
-import { _t } from "../../utils/I18nApi";
+import { _t } from "../../utils/i18n";

diff --git a/apps/web/src/settings/Settings.tsx b/apps/web/src/settings/Settings.tsx
--- a/apps/web/src/settings/Settings.tsx
+++ b/apps/web/src/settings/Settings.tsx
@@
+    "desktopProxyConfig": {
+        supportedLevels: [SettingLevel.PLATFORM],
+        displayName: _td("settings|network_proxy|title"),
+        default: {
+            mode: "system",
+        },
+    },

diff --git a/apps/web/src/i18n/strings/en_EN.json b/apps/web/src/i18n/strings/en_EN.json
--- a/apps/web/src/i18n/strings/en_EN.json
+++ b/apps/web/src/i18n/strings/en_EN.json
@@
+        "network_proxy": {
+            "connection_mode": "Connection mode",
+            "manual_configuration": "Manual configuration",
+            "mode_custom_selected": "Manual proxy configuration is enabled.",
+            "mode_direct_selected": "Direct connection is enabled. No proxy will be used.",
+            "mode_system_selected": "Using the system proxy configuration.",
+            "no_proxy_direct": "No proxy (direct connection)",
+            "no_proxy_for_comma_separated": "No proxy for",
+            "port": "Port",
+            "proxy_config_encrypted_system_storage": "Proxy password is stored in the system credential store when available.",
+            "proxy_host": "Proxy host",
+            "proxy_settings_updates_warning": "Changes apply to new network requests after saving.",
+            "settings_button": "Configure proxy",
+            "title": "Network Proxy",
+            "use_system_proxy": "Use system proxy"
+        },

6. I also found another proxy bug on the desktop side.
   With a custom proxy like 192.168.1.5:10808, the current code builds a rule like http=http://host:port.
   That only proxies plain HTTP, while HTTPS homeserver requests can still remain DIRECT, so the login/welcome flow can still fail even though a proxy was configured.
   I only got reliable login-page proxying locally after changing it like this:

diff --git a/src/proxy.ts b/src/proxy.ts
--- a/src/proxy.ts
+++ b/src/proxy.ts
@@
-        const scheme = cfg.scheme ?? "http";
-        parts.push(`${scheme}=${scheme}://${auth}${cfg.host}:${cfg.port}`);
+        const scheme = cfg.scheme ?? "http";
+        parts.push(`${scheme}://${auth}${cfg.host}:${cfg.port}`);

7. Logging out currently also wipes the saved desktop proxy config.
   From what I tested, after logging out, desktopProxyConfig disappears from the desktop profile, so the user is trapped again if the login screen still needs a proxy.
   The reason seems to be that the logout flow eventually calls desktop clearStorage(), which then calls Store.instance?.clear(), wiping the whole Electron store instead of only login/session-related data.

I think the proxy config should survive logout. For example:

• keep desktopProxyConfig out of the Store.instance?.clear() path, or
• store proxy settings in a separate desktop-only config file/store that is not cleared on logout.

For me, the main issue is that recovery is too hard when network access is broken. I think the login/welcome flow should still provide a way to change proxy and homeserver settings, similar to Telegram.

For reference, this is roughly how I built and tested the two PRs locally:

git clone https://github.com/element-hq/element-web.git
git clone https://github.com/element-hq/element-desktop.git

cd element-web
git fetch origin pull/32804/head:pr-32804
git checkout pr-32804
pnpm install
cp ../element-desktop/element.io/release/config.json ./apps/web/config.json
sed -i 's|from "../../utils/I18nApi"|from "../../utils/i18n"|' \
    packages/shared-components/src/settings/NetworkProxyView/NetworkProxyView.tsx
npx nx build element-web

cd ../element-desktop
git fetch origin pull/2827/head:pr-2827
git checkout pr-2827
pnpm install
rm -f webapp
ln -s ../element-web/apps/web/webapp ./webapp
pnpm run asar-webapp
pnpm run build
sudo apt install -y ./dist/element-desktop_1.12.12_amd64.deb

Please let me know if this is not the correct way to combine the two PRs for testing.

[t3chguy]

Sorry but you will need to merge these changes into element-hq/element-web#32804 apps/desktop