Labs/Sigma

Sigma is a platform to automatically install Labs approved add-ons and keep them up-to-date. The user-facing name of this add-on is Labs Pack.

A manifest is hosted on https://sigma.mozillalabs.com/ that controls the add-on behavior such as installing/uninstalling add-ons and showing informational pages. The manifest is only followed if a number of security checks pass such as a signature check. Some state is stored locally on each client that affects the add-on behavior.

Manifest Structure

The manifest is a JSON file with file extension .json where the top level JS object has the following properties:

infoUrl	string	Information url to open in a tab if different from the previous infoUrl
install	[objects]	Array of add-on objects to install (see below)
timestamp	Date (string)	Time when the manifest was created
uninstall	[strings]	Array of add-on id strings to uninstall

Install Add-on Object

The install array contains add-on objects with the following structure:

hash	string	Expected hash of the downloaded xpi structured as "<hash algorithm>:<hex hash value>" e.g., "sha256:a1b2c3..."
id	string	Add-on id to check if it's already installed locally
url	string	URL to fetch the .xpi to install the add-on
version	string	Version of the add-on to check if the local version is already current

Manifest Signature

At the same level as the .json file, there must be a .sig file that contains the expected signature of the plain-text JSON manifest that is verified by the public key, embedded in the add-on, corresponding to the private key used to sign the manifest.

Local State

In addition to the state of installed add-ons managed by Firefox, Sigma tracks the following values as preferences under the pref-branch extensions.sigma.:

disabledIds	JSON [strings]	Add-on ids of add-ons that were disabled when Sigma was disabled
infoUrl	string	Information url from the last successful manifest (copied from the infoUrl property)
installIds	JSON [strings]	Add-on ids from the last successful manifest (copied from the id property of the objects in the install property)
signature	string	Signature from the last successful manifest (copied from the .sig file)
test	boolean	User set preference to turn on testing against a test manifest/signature
timestamp	JSON Date	Timestamp from the last successful manifest (copied from the timestamp property)

Add-on Behavior

Sigma will automatically fetch and follow the manifest when triggered by a number of events.

Main Workflow

1. Download the .sig signature file
2. Check if the signature matches the local state signature
   1. If it matches, stop the update as the manifest and signature are unchanged
3. Download the .json manifest file
4. Check that the manifest and signature are correct with the embedded public key
   1. If the signature is not correct, abort
5. Check that the timestamp is a valid date
   1. If not or missing, abort
6. Check that the timestamp is at most 30 days old
   1. If it's too old, abort because we don't trust old manifests
7. Check that the timestamp is newer than the local state timestamp
   1. If it's older or the same, abort because we only trust newer manifests
8. Check if the infoUrl is different from the local state infoUrl
   1. If it is different, open a new tab with the new url and save infoUrl
9. For each add-on object in install, try to install the add-on if necessary
   1. Check if a local add-on exists with the id
      1. If it exists, check if it's newer or the current version
         1. If it's newer or current, don't re-install this add-on
   2. Check that the hash is a valid "algorithm:hex value" hash
      1. If it's not a valid hash, don't install this add-on
   3. Download the add-on .xpi at the url
   4. Check that the hash matches the computed hash for the .xpi
      1. If the hash does not match, don't install this add-on
   5. Install the add-on
10. For each add-on id in uninstall, uninstall if necessary
    1. Check if a local add-on exists with the add-on id
       1. If it exists, uninstall it
11. Save state (installIds, signature, timestamp) from the manifest now that we've followed the instructions