{"id":19388359,"url":"https://github.com/mk-fg/waterfox","last_synced_at":"2026-03-09T06:33:48.054Z","repository":{"id":144996950,"uuid":"226761550","full_name":"mk-fg/waterfox","owner":"mk-fg","description":"Various extensions and hacks that I use with Mozilla Firefox browser forks like Waterfox","archived":false,"fork":false,"pushed_at":"2025-06-24T15:11:56.000Z","size":459,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-24T16:27:10.088Z","etag":null,"topics":["bookmarklets","browser","configuration","firefox","webextensions"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"wtfpl","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mk-fg.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-12-09T01:44:07.000Z","updated_at":"2025-06-24T15:12:00.000Z","dependencies_parsed_at":"2024-01-10T15:45:04.994Z","dependency_job_id":"82d4c3ee-db80-418b-8f90-2e16c1a44584","html_url":"https://github.com/mk-fg/waterfox","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mk-fg/waterfox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk-fg%2Fwaterfox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk-fg%2Fwaterfox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk-fg%2Fwaterfox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk-fg%2Fwaterfox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mk-fg","download_url":"https://codeload.github.com/mk-fg/waterfox/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk-fg%2Fwaterfox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30284776,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T02:57:19.223Z","status":"ssl_error","status_checked_at":"2026-03-09T02:56:26.373Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bookmarklets","browser","configuration","firefox","webextensions"],"created_at":"2024-11-10T10:12:31.646Z","updated_at":"2026-03-09T06:33:48.035Z","avatar_url":"https://github.com/mk-fg.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"waterfox\n========\n\n.. contents::\n  :backlinks: none\n\nRepository URLs:\n\n- https://github.com/mk-fg/waterfox\n- https://codeberg.org/mk-fg/waterfox\n- https://fraggod.net/code/git/waterfox\n\n\n\nDescription\n-----------\n\nVarious extensions and hacks that I use with `Mozilla Firefox Browser`_\nforks like Waterfox_.\n\nNote that while Firefox is an okay modern browser, I wouldn't recommend using it\nin its original form, since same as vanilla Chrome/Chromium, it comes loaded with\nvarious adware and malware, due to commercial interests of parent org (Mozilla).\nWould suggest using stripped-down forks like Waterfox_ instead,\nor `Ungoogled Chromium`_ in case of Chrome/Chromium.\n\nOne important feature of such forks is that they allow tinkering with browser\nextensions freely, instead of forcing them to be installed only from \"official\"\nplace as-is, locked-down with mandatory centralized signing.\n\n.. _Mozilla Firefox Browser: https://www.mozilla.org/en-US/firefox/new/\n.. _Waterfox: https://www.waterfox.net/\n.. _Ungoogled Chromium: https://ungoogled-software.github.io/\n\n\n\nExtensions and tweaks for them\n------------------------------\n\nAny of these can be zipped into xpi like this::\n\n  % cd new-tab\n  % zip -r ~/Downloads/new-tab.xpi *\n\n| And then installed by simply opening (Ctrl+O) that file in waterfox.\n| This won't work in official FF due to hardcoded mandatory extension signing.\n|\n\nAll \\*.local addon patches are usually just a bunch of overlay/replacement\nfiles, which can be used to replace ones in original .xpi archive.\n\n\nnew-tab_\n````````\n.. _new-tab: new-tab\n\nSimple new-tab homepage with some non-eye-burning background image and JS checks\nfor some parameters in `arkenfox/user.js`_ or similar must-have settings preset,\nas well as testing AppArmor or similar confinement (via nativeMessaging_ call).\n\nI install user.js preset as vendor.js, so it'd be easy to diff or override via\nuser.js as necessary, but if waterfox screws up loading that, it might not be\nimmediately obvious, and same for LSM profiles, hence these simple checks in\nevery new tab, where problem would be immediately obvious.\n\nMain purpose though is to just make new tabs non-white, as whoever thought that\nwhite screen is an acceptable default was (or is) probably blind (by now) :)\n\nTabs will still momentarily flash white on opening though,\nwhich can be fixed by something like this in `userContent.css`_::\n\n  @-moz-document url-prefix(about:blank) {\n    body { background-color: #18343f !important; }\n  }\n\nNone of this would affect browser-start page btw, which can be changed via\nbrowser.startup.page + browser.startup.homepage in user.js, with latter being set to\nsomething like \"moz-extension://a1ae59a3-e618-4e86-441f-7202f3acf593/init.html\",\nwith extension UUID there from about:debugging or such.\n\nAlso, `userChrome.css`_ can be used to set bg color of that browser-start page::\n\n  .browserContainer { background-color: #18343f !important; }\n\nNot sure if it has to be this complicated to just have browser display something\nyou want in all tabs (and not blind you), but that's what seem to work atm\n(as of 2019, and still works for me in 2021, but maybe not all-necessary anymore).\n\nfs-access-check binary for confinement-test should be built from fs_access_check.c\n(see comments at the top there) and installed along with fs_access_check.json manifest\nfor nativeMessaging API calls to work - required since FF (rightfully) blocks any\ndirect file:// access from extensions.\n\n.. _arkenfox/user.js: https://github.com/arkenfox/user.js\n.. _nativeMessaging: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_messaging\n.. _UserContent.css: http://kb.mozillazine.org/index.php?title=UserContent.css\n.. _userChrome.css: https://www.userchrome.org/\n\n\nforce-english-language_\n```````````````````````\n.. _force-english-language: force-english-language\n\nForces Accept-Language and navigator.language(s) header/js values to identify\nbrowser as using english locale, despite privacy.resistFingerprinting setting\n(from e.g. `arkenfox/user.js`_) which hides this data.\n\nHelps to avoid sites presenting themselves in inconsistent languages based on\nIP or whatever else by default.\n\nThere is languageswitch_ addon which allows to change this lang on-the-fly,\nbut it doesn't work well with privacy.resistFingerprinting (e.g. only modifies header,\nbut does not add it), and is a lot more heavyweight than 10 JS lines here.\n\n.. _languageswitch: https://addons.mozilla.org/en-US/firefox/addon/languageswitch/\n\n\nflush-site-data_\n````````````````\n.. _flush-site-data: flush-site-data\n\n| **Does not seem to work well - leaves \"morgue\" files and HSTS/request caches behind.**\n| Might be fixable, see `github issue-2`_ for more details.\n|\n\nAdds button/hotkey (default - Alt+C) to flush all cache, cookies, localStorage,\nsessionStorage, indexedDB, serviceWorkers and pluginData - i.e. all tracking\nstuff that sites store in browser.\n\nAlternative to Ctrl + Shift + Delete firefox hotkey, but without prompting/checkboxes,\nand also clearing sessionStorage in all tabs.\n\nIt does not clear downloads/history, passwords and form autocomplete data\nthat is (almost entirely) used in the browser UI, not by websites.\n\n| Does not ask any questions or limits its scope in any way.\n| Useful to log out of everything, like closing/reopening private browser window.\n|\n\nLooking at other similar extensions, haven't found one that does good-enough cleanup,\nwhich seem to be pretty much this::\n\n  browser.browsingData.remove({}, { cache: true, cookies: true,\n      indexedDB: true, localStorage: true, serviceWorkers: true, ... })\n    .then(res =\u003e browser.tabs.query({}))\n    .then(tabs =\u003e tabs.forEach(\n      tab =\u003e browser.tabs.executeScript(tab.id, {code: 'sessionStorage.clear()'}) ))\n\nMost of them limit scope to list of domains derived from active tab,\nignore some stuff like localStorage, cache, indexedDB, or don't bother clearing\nsessionStorage in tabs.\n\nIssues 2s notification popup on success, and does console.error() on any failure.\n\n.. _github issue-2: https://github.com/mk-fg/waterfox/issues/2\n\n\nbookmark-toolbar-hotkeys_\n`````````````````````````\n.. _bookmark-toolbar-hotkeys: bookmark-toolbar-hotkeys\n\nOpens corresponding bookmarks or runs bookmarklets from Bookmark Toolbar\n(even when hidden) on Alt-F1, Alt-F2, etc keys, configurable via the usual\n\"Manage Extension Shortcuts\".\n\nSame idea as `bookmark-toolbar-shortcut`_ addon, but with support for ``javascript:...``\nbookmarklets_ (see `Bookmarklets to deal with annoying designs`_ post for some good examples),\nproper error handling/indication (via popup notification),\nand an updated manifest to include all permissions required for that.\n\nThis addon plus `bookmarklets.js`_ below provide an easy to tweak and use\nharness to run small javascript snippets in context of arbitrary pages on-demand,\nand can easily replace most of ad-hoc \"tweak/style page contents\" addons.\n\n.. _bookmark-toolbar-shortcut: https://github.com/nuchi/bookmark-toolbar-shortcut\n.. _Bookmarklets to deal with annoying designs: https://www.arp242.net/bookmarklets.html\n\n\nhttp-version-icon_\n``````````````````\n.. _http-version-icon: http-version-icon\n\nShows tiny colored h3/h2/spdy/old protocol icon in the URL bar on the right.\n\nChecks for HTTP version in \"HTTP/x 200 OK\" status line first,\nand then also `X-Firefox-{HTTP3,SPDY} headers`_ (not sure why those exist),\nsetting the indicator icon in the tab's URL bar accordingly.\n\nCan try it out on e.g. `http3.is page`_. Page reload (F5) might be needed\nfor FF to pickup/remember alt-svc header and start using QUIC connection for it.\n\nProtocol icons are tiny png files next to the script, which can be easily\nrecolored for specific theme background using ImageMagick_ command-line tools,\nfor example, to make all icons red::\n\n  % cd http-version-icon\n  % mogrify -channel R -evaluate set 65535 \\\n      -channel G -evaluate set 0 -channel B -evaluate set 0 *.png\n  % zip http-version-icon.xpi *.{png,js,json}\n\nThis works by setting red (R) color-channel value to max and G/B to 0 for all\npixels in all icon files, producing #FF0000 bright-red result. Note that\nImageMagick uses 0-65535 16b channels, not 0-255 8b ones like in hex notation.\n\nTo make a \"mogrify\" command for any other color values, following lines can be\nused in the python REPL (pops-up when running ``python`` w/o arguments)::\n\n  \u003e\u003e\u003e c = 17, 234, 120 ; n = (2**16 - 1) / 255\n  \u003e\u003e\u003e print(' '.join( f'-channel {c} -evaluate set {v}'\n        for c,v in zip('RGB', (round(n*c) for c in c)) ))\n\nThat will print mogrify-opts for rgb(17,234,120) color.\nUse e.g. ``c = b'\\x11\\xEA\\x78'`` to easily specify R,G,B channel values\nfrom a hexadecimal notation like #11EA78 instead.\n\n.. _X-Firefox-{HTTP3,SPDY} headers:\n  https://bugzilla.mozilla.org/show_bug.cgi?id=1696037\n.. _http3.is page: https://http3.is\n.. _ImageMagick: https://imagemagick.org/\n\n\nproxy-toggle.local_\n```````````````````\n.. _proxy-toggle.local: proxy-toggle.local\n\nIcons' tweak for proxy-toggle_ addon, replacing black ones with green/red ones,\ndepending on whether proxy is enabled/disabled (note - red=enabled).\n\nUseful with any dark background theme, which makes default all-black icons\nnearly invisible, plus color-coding is nice.\n\n.. _proxy-toggle: https://addons.mozilla.org/en-US/firefox/addon/proxy-toggle/\n\n\n\nMisc helpers\n------------\n\nVarious useful helper tools, data and configuration snippets.\n\n\nurl-handler.c_\n``````````````\n.. _url-handler.c: url-handler.c\n\nStrict URL-scheme-dispatcher binary for browser or similar link-clicky app.\n\nIntended to be assigned as a handler for e.g. \"magnet:\" and all other\nURL-schemes, to run some specific compiled-in app, depending on scheme in passed\nURL, kinda like xdg-open_.\n\nIt's especially handy to have single app for all of them with AppArmor and\nsimilar containers, where each external binary would have to be whitelisted.\nThis one can be assigned with no confinement there, and be reasonably relied\nupon to only run list of apps that were compiled-in, with URL as the only arg.\n\nTo assign handler app to a protocol in firefox,\nfirst add protocol scheme via about:config or `user.js`_::\n\n  user_pref(\"network.protocol-handler.expose.magnet\", false);\n\n| Now upon clicking that protocol link, FF will ask to specify handler app.\n| (can be changed later under \"Preferences - General - Applications\")\n|\n\nBuild this handler-wrapper with full list of all necessary handlers,\ne.g. \"mytorrent\" for \"magnet:\" and \"/opt/bin/mail-client\" for \"mailto:\" in this example::\n\n  % gcc -O2 \\\n    -Dh=magnet:mytorrent:mailto:/opt/bin/mail-client \\\n    -o url-handler url-handler.c\n  % strip url-handler\n\n(there's also an extra -Ddebug option to build it with \"verbose mode\" and\nprint additional info on scheme-matching process)\n\nAssign produced binary as a handler for clicked link, and it will run e.g.\n``/opt/bin/mail-client mailto:someone@gmail.com`` for all \"mailto:\" links from now on.\n\nBeing compiled C code, it is a very fast (\u003c1ms) and light wrapper (15K with glibc).\n\n.. _xdg-open: https://wiki.archlinux.org/index.php/Default_Applications\n.. _user.js: http://kb.mozillazine.org/User.js_file\n\n\nbookmarklets.js_\n````````````````\n.. _bookmarklets.js: bookmarklets.js\n\nRandom bookmarklets_ collected from somewhere or ad-hoc made to fix some local issue.\n\nThese are basically simple UserJS_ scripts that run on-demand (via button) in\npage context to tweak styles or layout, without the hassle of being tied to\nspecific domains or always running there, potentially slowing stuff down or\nbreaking things.\n\nGreat for a trivial in-page automation ops like \"remove all images\",\n\"clear all position=fixed elements\" or \"make text black/selectable/etc\",\nand very easy to make and edit on-the-fly for whatever comes to mind.\n\nOther bookmarklet collections that I've come across and borrowed from:\n\n- `alanhogan/bookmarklets`_\n- `loikein/geeky-bookmarklet-collection`_\n- `squarefree.com/bookmarklets`_\n\n.. _bookmarklets: https://en.wikipedia.org/wiki/Bookmarklet\n.. _UserJS: https://openuserjs.org/\n.. _alanhogan/bookmarklets: https://github.com/alanhogan/bookmarklets/\n.. _loikein/geeky-bookmarklet-collection: https://github.com/loikein/geeky-bookmarklet-collection\n.. _squarefree.com/bookmarklets: https://www.squarefree.com/bookmarklets/\n\n\n\nLinks to some external stuff I also use\n---------------------------------------\n\n- `arkenfox/user.js`_ - to disable misfeatures that creep into firefox over time.\n\n- ff-cli_ - command-line script to interact with firefox(-ish).\n\n  Allows to do things like list open tabs, bookmarks, compress/decompress\n  .mozlz4 files (e.g. ``search.json.mozlz4``) and such.\n\n- `AppArmor profile`_ - always nice to have for complex apps like browsers.\n\n  More restricted than common distro defaults, with no access to /home outside\n  of xdg junk dirs, profile and ~/Downloads, no access to devices, as well as\n  many other limitations for stuff I don't use myself.\n\n- Local `Waterfox Arch Linux PKGBUILD`_\n\n  | Builds it from .tar.gz release archive, not the humongous and slow git checkout.\n  | Can have some local patches/tweaks.\n\n- ca-certificates-whitelist-filter_ - tool to cleanup garbage certs from Web-PKI list\n  of root CAs, which is all but like 6-10 CAs used for everything (at least as of i2023).\n\n- cgrc_ - systemd-run wrapper for apps that can use some cgroup-limits, like browsers.\n\n  Has a bunch of extra functionality on top of systemd-run and generally usable\n  with just a slice + command name, instead of like 20 common/mandatory options\n  needed with raw systemd-run interface.\n\n- nbrpc_ - replacement for selective proxy enablement to route around various censorshit.\n\n.. _ff-cli: https://github.com/mk-fg/fgtk#ff-cli\n.. _AppArmor profile: https://github.com/mk-fg/apparmor-profiles/blob/master/profiles/waterfox\n.. _Waterfox Arch Linux PKGBUILD: https://github.com/mk-fg/archlinux-pkgbuilds/tree/master/waterfox\n.. _cgrc: https://github.com/mk-fg/fgtk#cgrc\n.. _nbrpc: https://github.com/mk-fg/name-based-routing-policy-controller\n\n\n\nLinks to other outdated stuff\n-----------------------------\n\nMostly scripts and such that I've used with pre-Quantum Firefox,\nwhich allowed much more customization and had many other diffs in general.\n\n- `ff_backup`_ - browser state tracking script, to auto-commit it into git by cron.\n\n  | For pre-57 firefox only, dumps opened tabs and data for a bunch of old addons.\n  | Generally useful for tab-hoarding and extensions with complex configurations/states.\n\n- firefox-homepage-generator_ - old firefox homepage generator.\n\n  Uses profile bookmarks and places dbs plus some other local data to produce\n  custom internet-index page with a bunch of links to browse.\n\n  Python2-based, also for old pre-58 FF versions.\n\n- `convergence`_ - fork of abandoned Convergence addon by Moxie Marlinspike.\n\n  Alternative mechanism for TLS cert validation, which uses distributed \"network\n  perspectives\" instead of centralized \"certificate authorities\".\n\n  \"Notaries\" (perspective-servers) must all agree on same cert signature for\n  IP/host + SNI, which is then cached in local sqlite db (for preformance/privacy)\n  and re-validated only when changed.\n\n  Did maintain working client/server setup of it for a few years and used it myself.\n\n  Was pretty good idea with absolutely terrible commercial CAs back in the day,\n  but less needed now with Certificate Transparency efforts and Let's Encrypt,\n  both mitigating main issues with such centralized model somewhat.\n\n  See `Certificate Pinner`_ addon for a modern, simpler and a bit more manual\n  opt-in solution for this task, or ca-certificates-whitelist-filter_ tool to\n  also do it system-wide.\n\n- redirector.ml_ - simple httpd I've used on localhost to work around firefox\n  search engine limitations of always quoting query string, to make e.g.\n  ``gh user/repo`` pseudo-search open ``github.com/user/repo`` URL,\n  via redirect from localhost that undoes url-quoting.\n\n  Not needed since I learned that you can put %s and %S into firefox bookmarks,\n  and add keywords to those, to exactly same effect, and without that limitation\n  with %S (%s - url-escaped, %S - as-is).\n  Also no need to edit search.json to effectively add new search engines that way.\n\n.. _ff_backup: https://github.com/mk-fg/fgtk#ff_backup\n.. _firefox-homepage-generator: https://github.com/mk-fg/firefox-homepage-generator\n.. _convergence: https://github.com/mk-fg/convergence\n.. _Certificate Pinner: https://gitlab.com/heurekus/certificate-pinner-for-firefox/\n.. _ca-certificates-whitelist-filter: https://github.com/mk-fg/ca-certificates-whitelist-filter\n.. _redirector.ml: https://github.com/mk-fg/waterfox/blob/70b9444/redirector.ml\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmk-fg%2Fwaterfox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmk-fg%2Fwaterfox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmk-fg%2Fwaterfox/lists"}