wt
d0c5fc5679
- add Chrome/Chromium Manifest V3 build with PAC proxy routing - keep Firefox Manifest V2 and Android compatibility - add Chromium API adapter and service worker - add Chrome build script and Makefile target - update README and add AGENT.md - document installation, signing, permissions, themes, and platform limitations
116 lines
5.4 KiB
Markdown
116 lines
5.4 KiB
Markdown
# 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.
|
|
- `<all_urls>` — apply the domain routing policy to web requests.
|
|
|
|
These permissions are used for proxy management. 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 Android 113 or newer. 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.
|
|
|
|
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: **1.0.1**
|