updated docs and added AGENT.md
This commit is contained in:
wt committed
1 parent
dded3d2fac
commit
11508e6740
2 files changed
+115
-71
No files matched your search
@@ -0,0 +1,45 @@
|
||||
# Project instructions
|
||||
|
||||
## Scope
|
||||
|
||||
This repository contains the Firefox WebExtension **Proxy Switcher Fork By WT**. It uses Manifest V2, a persistent background script, plain HTML/CSS/JavaScript, and no runtime dependencies.
|
||||
|
||||
## Source layout
|
||||
|
||||
- `manifest.json` — extension metadata, permissions, icons, popup, options page, and Firefox/Android compatibility.
|
||||
- `background.js` — proxy routing, proxy authentication, tab-domain tracking, and runtime message handling.
|
||||
- `config-manager.js` — local configuration storage and update API.
|
||||
- `popup.html`, `popup.js`, `popup.css` — current-domain quick controls.
|
||||
- `options.html`, `options.js`, `options.css` — profiles, domains, management actions, and Advanced Settings.
|
||||
- `icons/` — extension icon sizes referenced by `manifest.json`.
|
||||
- `Makefile` — build and cleanup commands.
|
||||
|
||||
## Development rules
|
||||
|
||||
- Keep all configuration local. Do not add telemetry, remote requests, analytics, or external script dependencies.
|
||||
- Preserve the `browser.*` WebExtension API style and Manifest V2 compatibility unless the task explicitly requests a migration.
|
||||
- Proxy settings are domain-specific. A missing domain entry means direct connection; an entry with `enabled: false` is configured but disabled.
|
||||
- Keep popup and options theme behavior consistent. Supported theme values are `system`, `light`, and `dark`.
|
||||
- When changing an icon, update every size referenced by the manifest and verify the XPI contains the new paths.
|
||||
- Never hand-edit or retain stale `META-INF` signatures after changing files. Build artifacts must be signed again before distribution.
|
||||
- Do not commit generated `web-ext-artifacts/` packages unless explicitly requested.
|
||||
|
||||
## Validation
|
||||
|
||||
Run these checks after source changes:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
Build a package with:
|
||||
|
||||
```sh
|
||||
make build
|
||||
```
|
||||
|
||||
The resulting XPI is written to `web-ext-artifacts/`. It is unsigned when produced by `web-ext build`; Android installation requires a package signed by Mozilla/AMO.
|
||||
@@ -1,99 +1,98 @@
|
||||
# Firefox Proxy Switcher
|
||||
|
||||
A Firefox extension that allows selective application of proxy servers to specific domains, providing flexible proxy management for different websites.
|
||||
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
|
||||
|
||||
- **Domain-specific proxy configuration**: Apply different proxy settings to different domains
|
||||
- **Proxy profiles**: Save and reuse proxy configurations
|
||||
- **HTTP and SOCKS5 support**: Support for both HTTP and SOCKS5 proxy types
|
||||
- **Authentication support**: Username/password authentication for proxies
|
||||
- **Tag-based organization**: Organize domains with custom tags
|
||||
- **Quick toggle**: Enable/disable proxy for domains with one click
|
||||
- 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.
|
||||
|
||||
## Security and Privacy
|
||||
## How it works
|
||||
|
||||
This extension is designed with user privacy and security in mind:
|
||||
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.
|
||||
|
||||
### Data Storage
|
||||
- All configuration data (domains, profiles, proxy settings) is stored locally in the browser using Firefox's `browser.storage.local` API
|
||||
- Proxy credentials (usernames/passwords) are encrypted and stored only in the local browser storage
|
||||
- No data is transmitted to external servers or collected by the extension
|
||||
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.
|
||||
|
||||
### Network Permissions
|
||||
The extension requests the following permissions necessary for its functionality:
|
||||
## Use the popup
|
||||
|
||||
- `proxy`: Required to configure and manage proxy settings
|
||||
- `storage`: Required to save user configuration locally
|
||||
- `tabs`: Required to determine the current domain when configuring proxy settings
|
||||
- `activeTab`: Required to access the current tab for configuration
|
||||
- `webRequest`: Required to handle proxy authentication requests
|
||||
- `webRequestBlocking`: Required to intercept and modify network requests for proxy routing
|
||||
- `<all_urls>`: Required to apply proxy settings to any website the user visits
|
||||
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.
|
||||
|
||||
### How Proxy Routing Works
|
||||
1. When a user visits a website, the extension checks if that domain has proxy configuration
|
||||
2. If configured, the extension routes the traffic through the specified proxy server
|
||||
3. If not configured, traffic uses the direct connection (no proxy)
|
||||
4. Authentication credentials are only used when required by the proxy server and are transmitted securely
|
||||
## Advanced Settings
|
||||
|
||||
### Security Considerations
|
||||
- **No data collection**: The extension does not collect, store, or transmit any browsing data
|
||||
- **Local-only storage**: All settings remain on the user's device
|
||||
- **Transparent operation**: Users can see exactly which domains use which proxies
|
||||
- **No external dependencies**: The extension works entirely offline once configured
|
||||
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
|
||||
|
||||
1. Download the extension package
|
||||
2. Open Firefox and navigate to `about:addons`
|
||||
3. Click the gear icon and select "Install Add-on From File"
|
||||
4. Select the downloaded extension file
|
||||
5. The extension will be installed and ready to use
|
||||
### Firefox desktop
|
||||
|
||||
For Firefox Android, install the signed XPI from the extension's AMO page or use
|
||||
Firefox's self-distributed add-on installation flow. The manifest declares Android
|
||||
compatibility through `browser_specific_settings.gecko_android`; unsigned local
|
||||
packages are still rejected by Firefox's extension signing policy.
|
||||
For a temporary development install:
|
||||
|
||||
### Advanced Settings
|
||||
1. Open `about:debugging#/runtime/this-firefox`.
|
||||
2. Select **Load Temporary Add-on**.
|
||||
3. Choose `manifest.json` or a freshly built XPI.
|
||||
|
||||
Open **Advanced Settings** from the extension popup to manage all domains and
|
||||
profiles. The **Theme** selector supports **System**, **Light**, and **Dark** and
|
||||
is stored locally for use in both the options page and popup.
|
||||
For a normal install, use an XPI signed by Mozilla/AMO. Firefox may reject an unsigned or stale-signed package.
|
||||
|
||||
## Usage
|
||||
### Firefox Android
|
||||
|
||||
### Basic Setup
|
||||
1. Click the Proxy Switcher icon in the Firefox toolbar
|
||||
2. Configure proxy settings for the current domain or access full settings
|
||||
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.
|
||||
|
||||
### Advanced Configuration
|
||||
1. Right-click the extension icon and select "Options"
|
||||
2. Add proxy profiles for reuse across domains
|
||||
3. Configure domain-specific proxy settings
|
||||
4. Use tags to organize your proxy configurations
|
||||
The `proxy.onRequest` API is supported on Firefox Android, but the extension still needs to be tested on the target Firefox version and device.
|
||||
|
||||
## Permissions Explanation
|
||||
## Build
|
||||
|
||||
### Required Permissions
|
||||
- **proxy**: Allows the extension to configure Firefox's proxy settings
|
||||
- **storage**: Enables saving your proxy configurations locally
|
||||
- **tabs**: Lets the extension know which domain you're currently viewing
|
||||
- **activeTab**: Provides access to the currently active tab for configuration
|
||||
- **webRequest**: Handles authentication with proxy servers
|
||||
- **webRequestBlocking**: Intercepts and routes network requests through proxies
|
||||
- **<all_urls>**: Applies proxy settings to any website you visit
|
||||
Install `web-ext`, then run:
|
||||
|
||||
All permissions are used solely for proxy management and do not enable data collection or tracking.
|
||||
```sh
|
||||
make build
|
||||
```
|
||||
|
||||
## Support
|
||||
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.
|
||||
|
||||
If you encounter issues or have questions:
|
||||
1. Check that all required permissions are granted
|
||||
2. Verify your proxy server settings are correct
|
||||
3. Ensure the proxy server is accessible from your network
|
||||
To remove generated packages:
|
||||
|
||||
## Version
|
||||
```sh
|
||||
make clean
|
||||
```
|
||||
|
||||
Current version: 1.0.1
|
||||
## 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**
|
||||
Reference in new issue
Block a user