99 lines
4.0 KiB
Markdown
99 lines
4.0 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.
|
|
|
|
## How it works
|
|
|
|
The background script listens to `browser.proxy.onRequest`. It extracts the request's origin domain and returns the matching proxy configuration. Domains without a configuration, and configured domains whose `enabled` value is `false`, 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 manifest declares `data_collection_permissions.required` as `none`.
|
|
|
|
## 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 `proxy.onRequest` API is supported on Firefox Android, but the extension still needs to be tested on the target Firefox version and device.
|
|
|
|
## 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.
|
|
|
|
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**
|