brave-backup/README.md

# Brave Settings Backup

## Quick: Manual intervention

When opening the browser using the backup, these are the only need actions:
- brave://settings/getStarted
    - Get started > On startup > Open the New Tab Page
- brave://settings/search
    - Set Search engine

## Explanation

Goal: Backup Brave Settings while disabling unnecessary features.

Resources at:
- Brave: https://support.brave.app/hc/en-us/articles/360039248271-Group-Policy
- Google: https://chromeenterprise.google/intl/en_us/policies/

### Using Group-Based Policies (GBP)

There are two groups:
    - Mandatory (system-wide) <- use this one
        - Stored at `/Library/Managed Preferences/com.brave.Browser.plist`
        - It is an editable file. This tool can be used too `PlistBuddy`
        - Commands:
            ```
            sudo mkdir -p "/Library/Managed Preferences"
            sudo chown root:wheel "/Library/Managed Preferences"
            sudo chmod 755 "/Library/Managed Preferences"

            # Run this see the effect
            sudo killall cfprefsd
            ```
    - Recommended (user-level)
        - Stored at: `~/Library/Preferences/com.brave.Browser.plist`
        - It is a binary and can be used via:
            - `defaults read com.brave.Browser`
            - `defaults delete com.brave.Browser`
            - `defaults write com.brave.Browser DefaultSearchProviderEnabled -bool true`
            - `defaults import com.brave.Browser ./com.brave.Browser.plist`

Some policies only work if the instance is managed via MDM.
Because of that, we have to rely on preferences too.

### Using Preferences

This method is not recommened neither is documented; however, there is no other alternative.

Whenever the browser is opened for the first time, this dir is created and populated:
- `~/Library/Application Support/BraveSoftware/Brave-Browser`

Note: For testing purposes, after everything is backed up, feel free to completely delete it.

Inside, there are four main files:
- `Brave-Browser/First Run` (empty file used as flag to skip "Welcome page")
- `Brave-Browser/Local State`
- `Brave-Browser/<Default_or_Profile>/Preferences`
- `Brave-Browser/<Default_or_Profile>/Secure Preferences`

How the browser starts up (as a new tab, for instance) and the default search engine are
preferences stored in "Secure Preferences", and these values are hashed to ensure the integrity.
This means that the file cannot be edited manually: only via UI or by backing up the whole file.
These hashes change based on the machine, so be aware.

## How does the backup work?

There are a few files:
```
.
├── _assets                         All settings.
│   ├── Default
│   │   └── Preferences
│   ├── First Run
│   └── Local State
├── assets                          Settings with hashes. Not important and can be deleted.
│   ├── Default
│   │   ├── Preferences
│   │   └── Secure Preferences
│   ├── First Run
│   └── Local State
├── policies                        Browser policies. Generated by `brave_set_policies.py`
│   └── com.brave.Browser.plist
├── README.md
├── brave_debug.sh
├── brave_set_assets.py             If `assets` dir not present, uses `_assets`.
├── brave_set_policies.py
└── brave_update_assets.sh
```

First, make sure to delete these files:
```
rm -rf ./assets
rm -rf '~/Library/Application Support/BraveSoftware/Brave-Browser'
```

Set `policies/com.brave.Browser.plist` by executing `./brave_set_policies.py`.
You can check them at: `brave://policy`.

Set `_assets` by executing `./brave_set_assets.py`.

Open the browser and manually follow the steps in "Manual intervention". Close the browser.

Run `./brave_update_assets.sh` to copy over `assets` the preferences with the new proper hashes.

## Debug or find new preferences

The script `./brave_debug.sh` helps finding the preference property by comparing the files.

After deleting the directory `~/Library/Application Support/BraveSoftware/Brave-Browser`,
open the browser (to load the `Brave-Browser` dir), close it and run `./brave_debug.sh backup init`.

Open agian the browser, change the desired settings, close it and run `./brave_debug.sh diff init`.

This will compare the old files with the new ones and help you find the differences.

The script basically creates named checkpoints in `/tmp`
following the structure `./brave_debug.sh <command> <checkpoint_name>`.

## All preferences files

- "Brave-Browser/Local State"
    - Create empty file "Brave-Browser/First Run"
    - Check asset file

- "Brave-Browser/Default/Preferences"
    - Check asset file

- "Brave-Browser/Default/Secure Preferences"
    - Search engine is set in "Default/Preferences" but unless
      it is hashed in "Default/Secure Preferences", browser does not set it.
    - `restore_on_startup: 5` sets "On startup: Open the New Tab Page". It needs to be hashed too.
    ```
    {
      "session": {
        "restore_on_startup": 5
      }
    }
    ```

## All settings mapped

---
Brave 1.83.118 (Official Build) (arm64)
Chromium: 141.0.7390.108
---

### Get started
- On startup >> "Open the New Tag page"
	- [Secure Preferences]:session.restore_on_startup
- New tab page shows >> "Blank page"
	- brave.new_tab_page.shows_options

### Appearance
- Show tab groups in bookmarks >> OFF
	- bookmark_bar.show_tab_groups
- Automatically pin new tab groups created on any device to the bookmarks >> OFF
	- auto_pin_new_tab_groups

### Shields
- Show the number of blocked items on the Shields icon >> OFF
	- brave.shields.stats_badge_visible
- Store contact information for future broken site reports >> OFF
	- brave.webcompat.report.contact_info: "" (empty string)
	- brave.webcompat.report.enable_save_contact_info: false

### Privacy and security
- Only resolve .onion addresses in Tor windows >> OFF
	- tor.onion_only_in_tor_windows
- Allow privacy-preserving product analytics (P3A) >> OFF
	- [Local State]:brave.p3a.enabled
- Automatically send diagnostic reports >> OFF
	- [Local State]:brave.user_experience_metrics.reporting_enabled

### Search engine
- Improve search suggestions >> OFF
	- search.suggest_enabled

### Extensions
- Media Router >> OFF
	- media_router.enable_media_router
- Widevine >> ON
	- brave.widevine_opted_in

### Autofill and passwords
- (Passwords.Settings) Sign in automatically >> OFF
	- credentials_enable_autosignin
- Allow auto-fill in private windows >> OFF
	- brave.autofill_private_windows

### Languages
- Websites in your languages >> "en"
	- intl.accept_languages
	- intl.selected_languages

### System
- Memory Saver >> ON
	- [Local State]:performance_tuning.high_efficiency_mode
- Energy Saver >> OFF
	- [Local State]:performance_tuning.battery_saver_mode