# Firefox Proxy Switcher Proxy Switcher is a Firefox WebExtension that routes requests for selected domains through HTTP or SOCKS5 proxies. Settings and proxy credentials stay in Firefox local extension storage. ## Features - Configure a different proxy for each domain. - Use HTTP or SOCKS5 proxies. - Store optional proxy username and password per domain. - Save reusable proxy profiles. - Enable or disable a configured domain from the popup. - Search domains and filter them by tags. - Choose a **System**, **Light**, or **Dark** theme in Advanced Settings. - Use the same theme in the options page and popup. - Run on Firefox desktop and Firefox Android versions that support the declared minimum version. - Build a separate Manifest V3 package for Chrome and Chromium-based desktop browsers. ## How it works On Firefox, the background script listens to `browser.proxy.onRequest`. On Chrome and Chromium, the background service worker generates a PAC script through `chrome.proxy.settings`. Both implementations extract the request host and route only enabled matching domains; all other domains use a direct connection. Proxy authentication is supplied only when the matching domain has credentials. The extension does not collect browsing history or send configuration to a server. Domain entries, profiles, theme selection, and credentials are saved with `browser.storage.local`. The extension does not implement an additional encryption layer, so protect the Firefox profile and device that contain the data. ## Use the popup 1. Open a website and click the Proxy Switcher toolbar button. 2. If the domain already has a configuration, use **Use proxy for this domain** to enable or disable it. 3. For a new domain, enable the switch, enter the proxy host and port, then select **Apply & Reload**. 4. Open **Advanced Settings** for the complete domain and profile manager. ## Advanced Settings The options page provides: - Proxy profiles that can be reused while editing domains. - Domain entries with proxy type, host, port, optional credentials, tags, and enabled state. - Search and tag filtering. - Bulk deletion of domains, profiles, or all extension data. - Theme selection: **System**, **Light**, or **Dark**. ## Permissions The manifest requests these permissions: - `proxy` — route requests through the selected proxy. - `storage` — store domains, profiles, theme, and credentials locally. - `tabs` and `activeTab` — identify the active tab's domain and reload it after changes. - `webRequest` and `webRequestBlocking` — provide proxy authentication credentials. - `` — apply the domain routing policy to web requests. These permissions are used for proxy management. The manifest declares `data_collection_permissions.required` as `none`; the extension does not collect or transmit data. ## Installation ### Firefox desktop For a temporary development install: 1. Open `about:debugging#/runtime/this-firefox`. 2. Select **Load Temporary Add-on**. 3. Choose `manifest.json` or a freshly built XPI. For a normal install, use an XPI signed by Mozilla/AMO. Firefox may reject an unsigned or stale-signed package. ### Firefox Android Firefox Android requires a signed extension package. Submit the build through [addons.mozilla.org/developers](https://addons.mozilla.org/developers/) and download the signed XPI after review, or follow Mozilla's [self-distributed extension instructions](https://extensionworkshop.com/documentation/publish/install-self-distributed/). The manifest includes `browser_specific_settings.gecko_android` so AMO can mark the extension as Android-compatible. The manifest targets Firefox 140+ on desktop and Firefox Android 142+. The `proxy.onRequest` API is supported there, but the extension still needs to be tested on the target Firefox version and device. ### Chrome and Chromium desktop Chrome and Chromium do not use the Firefox proxy API, so the project includes a separate Manifest V3 package. It works on desktop Chrome, Chromium, Edge, Brave, Opera, and other Chromium browsers that expose the `chrome.proxy` API. Chrome Android and Chrome iOS do not support installing ordinary extensions; this project cannot enable extensions on those platforms. Build and install the unpacked package: ```sh make build-chrome ``` Then open `chrome://extensions` (or the equivalent page), enable **Developer mode**, and select **Load unpacked** using a directory containing the Chrome build. The ZIP at `web-ext-artifacts/proxyswitcherforkbywt-chrome.zip` can be uploaded to the Chrome Web Store or unpacked for local testing. The Chrome build uses a PAC script because Chrome's proxy API is global rather than Firefox's per-request `proxy.onRequest` API. Changing a proxy configuration regenerates that PAC script. Chrome proxy credentials are provided through `webRequest.onAuthRequired`. ## Build Install `web-ext`, then run: ```sh make build ``` The package is created at `web-ext-artifacts/proxyswitcherforkbywt.xpi`. This local build is not an AMO signature. After changing any file, rebuild and sign again; do not reuse old `META-INF` signature files. For Chrome/Chromium, run `make build-chrome`. That creates `web-ext-artifacts/proxyswitcherforkbywt-chrome.zip` from `manifest.chrome.json` and the shared UI files. ## GitHub Actions release publishing `.github/workflows/release.yml` builds both packages on every push. The run exposes a downloadable `extension-packages-` artifact containing the Firefox XPI and Chrome ZIP. When a GitHub Release is published, it checks that both manifests match the release tag, submits the Firefox package to AMO for signing and review, uploads and submits the Chrome package through the Chrome Web Store API v2, and attaches the signed Firefox XPI and Chrome ZIP to the release card. Configure these repository or environment secrets before publishing: - `AMO_JWT_ISSUER` and `AMO_JWT_SECRET` — AMO API credentials for `web-ext sign`. - `CWS_PUBLISHER_ID` and `CWS_EXTENSION_ID` — Chrome Web Store publisher and existing item IDs. - `CWS_CLIENT_ID`, `CWS_CLIENT_SECRET`, and `CWS_REFRESH_TOKEN` — Google OAuth credentials with Chrome Web Store API access. Each store is optional: deployment runs only when its full set of credentials is present. Missing or incomplete credentials skip that store without failing the workflow or skipping the other store. Both packages are still built and attached to the release. If Firefox deployment is skipped, the release contains the unsigned Firefox XPI for development instead of a signed XPI. Invalid credentials or actual store API failures still fail the deployment step. AMO can create the initial listing automatically from `amo-metadata.json` through `web-ext sign --channel listed`; manually uploading the first Firefox version is not required. Chrome Web Store requires an existing item and completed listing/privacy information. Store review still applies; the workflow submits the update and does not bypass review. Never commit any of these credentials. The Firefox workflow passes [`amo-metadata.json`](amo-metadata.json) to AMO. It declares the MIT license, categories, and listing metadata for a listed submission. To remove generated packages: ```sh make clean ``` ## Validation ```sh node --check background.js node --check config-manager.js node --check popup.js node --check options.js python -m json.tool manifest.json >/dev/null ``` ## Project version Current version: **20261009.1** ## License Distributed under the [MIT License](LICENSE).