Add readme

1 files changed, 92 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c7fe43d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,92 @@
+# firefox-profiles
+
+This repository attempts to provide tooling to aid the configuration of Firefox,
+and offers multiple profiles which sacrifice convenience and sometimes security
+in favor of data frugality.
+
+## Required tooling
+
+- [Nix](https://nixos.org/nix/), which offers a very convenient way of working with
+  deeply nested attribute sets, including composing and generating them.
+
+  - Nix is used here to build the Firefox configuration, to bundle it with nixpkgs-provided Firefox,
+    and to provide a wrapper to quickly test configuration changes with temporary profiles.
+    A deployment path without the installation of Nix on the managed devices is plausible,
+    only the administrator will need to have it installed.
+
+## Usage
+
+```bash
+# this launches a configured instance
+$(nix-build --no-out-link -A launcher)/bin/firefox
+```
+
+## Configuration approach
+
+Firefox exposes two different types of settings:
+
+- [*Preferences*](https://developer.mozilla.org/en-US/docs/Mozilla/Preferences/A_brief_guide_to_Mozilla_preferences): Key value pairs, e.g. `browser.cache.disk.enable` or `browser.search.defaultenginename`
+  - These are inspectable by visiting `about:config`
+  - I don't expect a lot of interface stability here
+
+- [Enterprise policies](https://github.com/mozilla/policy-templates/)
+  - [Via `org.mozilla.firefox.plist` for macOS](https://support.mozilla.org/en-US/kb/customizing-firefox-macos-using-configuration-prof)
+  - [Via AD and "Local Group Policy" for Windows](https://support.mozilla.org/en-US/kb/customizing-firefox-using-group-policy-windows)
+  - [Using `policies.json` as the only cross-platform method](https://support.mozilla.org/en-US/kb/customizing-firefox-using-policiesjson)
+  - Despite the warning, they seem intended to be a more stable interface
+  - They offer limited access to the key value pairs mentioned above, exposing
+    a subset of them as [Preferences](https://github.com/mozilla/policy-templates/#preferences)
+
+As far as I can tell, the primary methods of configuration are:
+
+- The Firefox profile, stored in **~/.mozilla/firefox/something.default**
+  - **prefs.js**: This file contains interactively set configuration variables.
+    It is overwritten frequently and should not be modified from applications that
+    are not Firefox.
+  - **user.js**: A configuration file similar to `prefs.js`, but it is never written
+    to by Firefox, and is loaded after `prefs.js`, which means preferences defined
+    here take precedence.
+
+- The Firefox distribution, created either by Mozilla directly, or by your
+  favorite Linux distribution package maintainers
+  - `$FIREFOX_EXECUTABLE/../lib/firefox/distribution/policies.json`: Allows defining enterprise policy settings,
+    which are applied to any instance launched from `$FIREFOX_EXECUTABLE`.
+  - `$FIREFOX_EXECUTABLE/../lib/firefox/defaults/pref/*.js`: These files are executed on every launch, and can
+    serve as an alternative to `user.js`
+  - `$FIREFOX_EXECUTABLE/../lib/firefox/browser/omni.ja`: Contains bundled resources and scripts, which are given
+    special permissions in some situations (e.g. pre-configuring a default search engine).
+
+For this project, I decided against `user.js` for the following reasons:
+
+- It's not recommended by Mozilla, I've seen enterprise policies recommended more often for shipping
+  preconfigured instances.
+- Preconfiguration via `user.js` would require copying into every profile of every user it should apply to,
+  which requires either a wrapper script or a daemon to watch for new profile creations.
+- The `user.js` files in the users profile directory are editable by users, and every process they execute.
+  This can be exploited to e.g. configure a socks proxy and spy on users without their knowledge.
+- [Future support for configuration via user.js is uncertain](https://bugzilla.mozilla.org/show_bug.cgi?id=1543752)
+- Installation-wide configuration should happen centrally, not in a dozen places all over /home.
+
+Meanwhile, enterprise policies seem to enjoy more direct support from Mozilla, are applied to any profile launched
+with the bundled Firefox, and the bundled preference files are not editable by ordinary user processes.
+
+Depending on the selected profiles, a combination of enterprise profiles, a bundled settings file in `lib/firefox/defaults/pref/*.js`,
+and even patching of `omni.ja` is applied in order to achieve their goal.
+
+## Qwant Junior
+
+I built a minimal extension to add Qwant Junior as a search engine in `profiles/addons/qwantjunior`.
+
+Mozilla tried very hard to prevent the preconfiguration of bundled default search engines, and the only way
+to do so (as far as I could tell), is to install the extension into FFs built-in extensions. Being a built-in
+extension bypasses the prompt asking the user whether to allow setting a default search engine.
+
+The extension works Fine™ if installed ordinarily, but it prompts the user with a dialog on the first start,
+which had a bug in my testing, and I needed to be careful to prevent accidental dismissal.
+
+And yes, Firefox refuses to load the addon if the id doesn't match `*@search.mozilla.org`.
+
+## Known issues
+
+- With this first attempt, usage errors can be silently ignored, which is probably going to be quite irritating for any non-Nix people.
+  - I plan to migrate this to Nix modules, which should result in a much better configuration exprience.