From 0391f9f4332aebc5c5a30ed4d1a086ac76dc472e Mon Sep 17 00:00:00 2001 From: erosman Date: Sat, 19 Oct 2024 21:26:59 +0330 Subject: [PATCH] Update README.md --- README.md | 316 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 314 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d924bbd..74439a7 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,125 @@ -# ![FireMonkey](/src/image/icon.svg) FireMonkey UserScript & UserCSS Manager +# ![FoxyProxy](/src/image/icon.svg) FoxyProxy Browser Extension + +[![license](https://img.shields.io/github/license/foxyproxy/browser-extension.svg)](https://github.com/foxyproxy/browser-extension/blob/master/LICENSE) +![GitHub repo size](https://img.shields.io/github/repo-size/foxyproxy/browser-extension?logo=github&logoColor=fff) +![ECMAScript](https://img.shields.io/badge/ECMAScript-2022_(ES13)-blue?style=plastic&logo=javascript) + + + +[About/Changelog](https://foxyproxy.github.io/browser-extension/src/content/about.html) | [Help](https://foxyproxy.github.io/browser-extension/src/content/help.html) | [Issues](https://github.com/foxyproxy/browser-extension/issues) + +After some years of stability, FoxyProxy has been updated to support Manifest Version 3 which is required by Chrome in order for extensions to be compatible with Chrome in 2024. We took advantage of this forced update to implement many feature requests and other changes that were requested over the years. + +FoxyProxy has been owned and developed consistently by the same team since 2006. + +The repository has the source code for version 8.0+ for *Firefox*, *Chrome*, and other Chromium-based browsers like *Chromium*, *Brave* and *Edge*. Source code for [older versions](https://github.com/foxyproxy/firefox-extension). + +## Permissions + +- **downloads**: Used to save/export user preferences to file, for backup or sharing +- **notifications**: Used to inform users (e.g. for errors) +- **proxy**: Used to set proxies (core function of the extension) +- **storage**: Used to store user preferences +- **tabs**: Used to get tab details (e.g. for "Quick Add", "Tab Proxy", & "Incognito/Container Proxy") +- **webRequest**: Used to provide proxy authentication +- **webRequestAuthProvider**: Used to provide proxy authentication +- **host permission**: Used to provide proxy authentication (to any URL `""`) + +#### Optional Permissions + +- **browsingData**: Used for "Delete Browsing Data" button to delete cookies, indexedDB, and localStorage, only if requested by the user +- **privacy**: Used for "Limit WebRTC" button to toggle `browser.privacy.network.webRTCIPHandlingPolicy`, only if requested by the user + +## Mini FAQ + +- **Why is there a [CryptoJS](https://code.google.com/archive/p/crypto-js/) library in [lib](https://github.com/foxyproxy/browser-extension/tree/main/src/lib)?**
+The CryptoJS library was already included in [FoxyProxy 3.x](https://github.com/foxyproxy/Foxyproxy_Chrome/blob/f1bca1c50dfa30908c79a9ea477f31eda2abacf4/app/scripts/stored-credentials.js#L4) to encrypt user credentials. It is needed to migrate encrypted settings from the old version (which had no updates for many years, as you mentioned). It is not used to encrypt anything; only to decrypt old data when upgrading from version 3.x to 8.x.
+The library is not used in Firefox, and will be removed once users migrate to v8+. + +- **Remote Code**
+No remote code is used in this extension. + +## Screenshots + +### Dark Theme + + + + + +### Light Theme + + + + + +## Releases + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ChromeFirefoxEdge
Standard +
+ + 		+
+ + + 		+

+
Basic +
+ + 		+
+ + +
Source Code Beta
Source Code ReleaseReleases
Source Code Old3.0.7.17.5.1
+ + +### Browser Minimum + + + + + + + + # ![FireMonkey](/src/image/icon.svg) FireMonkey UserScript & UserCSS Manager [![license](https://img.shields.io/github/license/erosman/firemonkey.svg)](https://github.com/erosman/firemonkey/blob/master/LICENSE) ![GitHub repo size](https://img.shields.io/github/repo-size/erosman/firemonkey?logo=github&logoColor=fff) @@ -6,7 +127,7 @@ [About/Changelog](https://erosman.github.io/firemonkey/src/content/about.html) | [Help](https://erosman.github.io/firemonkey/src/content/help.html) | [Issues](https://github.com/erosman/firemonkey/issues) -FireMonkey is a totally new combined user-script and user-style manager. While it has similar functions to other user-Script managers like Greasemonkey/Tampermonkey/Violentmonkey, and user-style managers like Stylish/Stylus/xStyle, there are also differences. +FireMonkey is a totally new combined user-script and user-style manager. While it has similar functions to other user-Script managers like Greasemonkey/Tampermonkey/Violentmonkey, and user-style managers like Stylish/Stylus/xStyle, there are also differences. Similar to other userscript managers, scripts (or CSS) are injected in tabs when tab is reloading. ## Permissions @@ -70,3 +191,194 @@
ChromeFirefoxFirefox for Android
+ + + + version 108
(released 2022-11-29) + version 93
(released 2021-10-05) + version 113 (manifest)
(API minimum 102) + + + + + +## Beta Installation Guide +- Backup your FoxyProxy settings +- Download repo *(or use `git`)* + - browser-extension *(this page)* -> Code *(green button)* -> Download ZIP + - Unzip the downloaded file + +- **Chrome** + - Rename `manifest-chrome.json` in `src` folder to `manifest.json` + - Go to `chrome://extensions/` + - Enable Developer Mode *(top right)* + - Click "Load Unpacked" + - Select above `manifest.json` *(or `src` folder)* + +- **Firefox** *(Nightly/Beta/Developer Edition)* + - Rename `manifest-firefox.json` in `src` folder to `manifest.json` + - Go to `about:debugging#/runtime/this-firefox` + - Click "Load Temporary Add-on..." + - Select above `manifest.json` + +- **Firefox for Android** + - Install Firefox Nightly + - [Firefox Nightly for Developers](https://play.google.com/store/apps/details?id=org.mozilla.fenix&hl=en&gl=US) + - Enable Debug Menu + - Go to: menu -> Settings -> About Firefox Nightly + - Tap a few times on the Firefox icon to enable debug menu + - Go to: `about:config` + - Find `xpinstall.signatures.required` + - Toggle to `false` + - Install Beta version + - Prepare `src` for Firefox as mentioned above + - Create a zip file from the content of `src` + - Make the file available to the Android device + - Install add-on from file + - Go to: menu -> Settings -> Advanced -> Install add-on from file + +## Building for Distribution + +### With [grunt](https://gruntjs.com/getting-started): + +- Install grunt locally: + - `npm i -D grunt-cli` +- Run one of: + - `grunt --target=chrome-standard`
+ - `grunt --target=chrome-basic`
+ - `grunt --target=firefox-standard`
+ - `grunt --target=firefox-basic` + +The target is built in `foxyproxy-XXX-YYY.zip`; e.g. `foxyproxy-chrome-standard.zip`. + +### Without grunt: + +- copy the appropriate manifest-xxx.json file to manifest.json; e.g. `mv manifest-chrome.json manifest.json` +- zip the `src` directory into the top of an archive. The `src/` directory should **not** be in the zip archive. + +--- + +# FAQ + +## 💻 Settings disappeared after the upgrade to v8 + +Using Firefox and you've lost all FoxyProxy settings? + +FoxyProxy Basic 8.0 was first released in Sep 2023 as a trial run since it had fewer users (26k on Chrome & Firefox). +We waited for 2 months for any feedback & bug reports before releasing FoxyProxy Standard. +Unfortunately, we didn't get any bug report about the data migration sync issue, otherwise we would have fixed it before releasing the standard version. +FoxyProxy 8.2 went online on Dec 6th. +Due to a bug in version 8.2, previous settings of some users were not migrated after the upgrade. +Versions 8.3-8.6 created with fixes for the bugs immediately, but due to the AMO approval waiting time, version 8.6 came online on Dec 12th. + +Previous settings were not deleted and are recoverable. The following options are available if FoxyProxy updated from 7.* and you have encountered the update bug. + +
+ Retrieve Settings and Keep version 8.2 + +From [this comment](https://github.com/foxyproxy/browser-extension/issues/45#issuecomment-1838719332): + +### Look for old data + +1. Go to the FoxyProxy Options page +2. Open the Dev Tools (F12) +3. Go to the Console tab +4. Type the following and hit ENTER + + +### With Sync + +```js + browser.storage.sync.get().then(console.log) +``` + +If above has some data, then in the Console tab, type the following and hit ENTER + +```js +browser.storage.sync.get().then(pref => { + const data = JSON.stringify(pref, null, 2); + const blob = new Blob([data], {type: 'application/json'}); + browser.downloads.download({ + url: URL.createObjectURL(blob), + filename: 'FoxyProxy_sync.json', + saveAs: true, + conflictAction: 'uniquify' + }) + .catch(() => {}); +}); +``` + +### Without Sync + +```js + browser.storage.local.get().then(console.log) +``` + +If above has some data, then in the Console tab, type the following and hit ENTER + +```js +browser.storage.local.get().then(pref => { + const data = JSON.stringify(pref, null, 2); + const blob = new Blob([data], {type: 'application/json'}); + browser.downloads.download({ + url: URL.createObjectURL(blob), + filename: 'FoxyProxy_local.json', + saveAs: true, + conflictAction: 'uniquify' + }) + .catch(() => {}); +}); +``` +### Import data + +1. Go to **Import Tab -> Import from older versions** +2. Import the `FoxyProxy_sync.json` or `FoxyProxy_local.json` file that you have saved +3. Click SAVE to save the data +
+ +
+ Downgrade to 7.* + +Downgrade may retrieve old settings. + +1. Download 7.5.1 (or older) from https://addons.mozilla.org/firefox/addon/foxyproxy-standard/versions/ +2. Click the file; firefox will ask you to install that addon. Confirm +3. Go to Firefox settings, addons (about:addons), FoxyProxy, check that it shows version 7.* +4. **Important**: On that same page, set "Allow automatic updates" to off + +The settings bug is expected to be fixed in the latest release. +Check [About](https://foxyproxy.github.io/browser-extension/src/content/about.html) for more information. + +
+ + + + +## 📱 Firefox for Android + +Firefox for Android ignored disabling `extensions.update.enabled` (due to a [bug](https://bugzilla.mozilla.org/show_bug.cgi?id=1872169)). Therefore, installation of an older version from AMO will get updated. The bug is fixed in Firefox 123. + +
+ Downgrade ot Beta Installation + + +- Download 7.5.1 (or older) from https://addons.mozilla.org/firefox/addon/foxyproxy-standard/versions/ + - Make the file available to the Android device through [Android File Transfer](https://www.android.com/filetransfer/), adb, Android Studio, or a similar tool +- Install [Firefox Nightly for Developers](https://play.google.com/store/apps/details?id=org.mozilla.fenix&hl=en&gl=US) on Android +- Enable Debug Menu + - Go to:` menu -> Settings -> About Firefox Nightly` + - Tap a few times on the Firefox icon to enable debug menu +- Navigate to: `about:config` + - Find `xpinstall.signatures.required` + - Toggle to `false` + - Find (or add) `extensions.update.enabled` + - Toggle to `false` + - Install add-on from file + - Go to: `menu -> Settings -> Advanced -> Install add-on from file` and select the `.zip` file you transferred to the android device + - Check "Allow in private browsing" then "Okay, Got it" + +#### See also: +- [Downgrade instructions](https://github.com/foxyproxy/browser-extension/issues/107) +- [Beta instructions](https://github.com/foxyproxy/browser-extension#beta-installation-guide) + +