From 11508e6740c6d4346b2aa79e6912e668f1bb9dec Mon Sep 17 00:00:00 2001 From: wt Date: Fri, 9 Oct 2026 16:00:18 +0700 Subject: [PATCH] updated docs and added AGENT.md --- AGENT.md | 45 +++++++++++++++++ README.md | 141 +++++++++++++++++++++++++++--------------------------- 2 files changed, 115 insertions(+), 71 deletions(-) create mode 100644 AGENT.md diff --git a/AGENT.md b/AGENT.md new file mode 100644 index 0000000..7f14672 --- /dev/null +++ b/AGENT.md @@ -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. diff --git a/README.md b/README.md index 34b02d5..b72cf1c 100644 --- a/README.md +++ b/README.md @@ -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 -- ``: 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. +- `` — 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 -- ****: 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**