Adding upstream version 110.0.1.upstream/110.0.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

19 files changed, 4378 insertions, 0 deletions

diff --git a/toolkit/components/normandy/lib/ActionsManager.jsm b/toolkit/components/normandy/lib/ActionsManager.jsm
new file mode 100644
index 0000000000..ae83f96ef1
--- /dev/null
+++ b/toolkit/components/normandy/lib/ActionsManager.jsm
@@ -0,0 +1,105 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this file,
+ * You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+const { XPCOMUtils } = ChromeUtils.importESModule(
+  "resource://gre/modules/XPCOMUtils.sys.mjs"
+);
+const { LogManager } = ChromeUtils.import(
+  "resource://normandy/lib/LogManager.jsm"
+);
+
+const lazy = {};
+
+XPCOMUtils.defineLazyModuleGetters(lazy, {
+  AddonRollbackAction: "resource://normandy/actions/AddonRollbackAction.jsm",
+  AddonRolloutAction: "resource://normandy/actions/AddonRolloutAction.jsm",
+  BaseAction: "resource://normandy/actions/BaseAction.jsm",
+  BranchedAddonStudyAction:
+    "resource://normandy/actions/BranchedAddonStudyAction.jsm",
+  ConsoleLogAction: "resource://normandy/actions/ConsoleLogAction.jsm",
+  MessagingExperimentAction:
+    "resource://normandy/actions/MessagingExperimentAction.jsm",
+  PreferenceExperimentAction:
+    "resource://normandy/actions/PreferenceExperimentAction.jsm",
+  PreferenceRollbackAction:
+    "resource://normandy/actions/PreferenceRollbackAction.jsm",
+  PreferenceRolloutAction:
+    "resource://normandy/actions/PreferenceRolloutAction.jsm",
+  ShowHeartbeatAction: "resource://normandy/actions/ShowHeartbeatAction.jsm",
+  Uptake: "resource://normandy/lib/Uptake.jsm",
+});
+
+var EXPORTED_SYMBOLS = ["ActionsManager"];
+
+const log = LogManager.getLogger("recipe-runner");
+
+/**
+ * A class to manage the actions that recipes can use in Normandy.
+ */
+class ActionsManager {
+  constructor() {
+    this.finalized = false;
+
+    this.localActions = {};
+    for (const [name, Constructor] of Object.entries(
+      ActionsManager.actionConstructors
+    )) {
+      this.localActions[name] = new Constructor();
+    }
+  }
+
+  static actionConstructors = {
+    "addon-rollback": lazy.AddonRollbackAction,
+    "addon-rollout": lazy.AddonRolloutAction,
+    "branched-addon-study": lazy.BranchedAddonStudyAction,
+    "console-log": lazy.ConsoleLogAction,
+    "messaging-experiment": lazy.MessagingExperimentAction,
+    "multi-preference-experiment": lazy.PreferenceExperimentAction,
+    "preference-rollback": lazy.PreferenceRollbackAction,
+    "preference-rollout": lazy.PreferenceRolloutAction,
+    "show-heartbeat": lazy.ShowHeartbeatAction,
+  };
+
+  static getCapabilities() {
+    // Prefix each action name with "action." to turn it into a capability name.
+    let capabilities = new Set();
+    for (const actionName of Object.keys(ActionsManager.actionConstructors)) {
+      capabilities.add(`action.${actionName}`);
+    }
+    return capabilities;
+  }
+
+  async processRecipe(recipe, suitability) {
+    let actionName = recipe.action;
+
+    if (actionName in this.localActions) {
+      log.info(`Executing recipe "${recipe.name}" (action=${recipe.action})`);
+      const action = this.localActions[actionName];
+      await action.processRecipe(recipe, suitability);
+
+      // If the recipe doesn't have matching capabilities, then a missing action
+      // is expected. In this case, don't send an error
+    } else if (
+      suitability !== lazy.BaseAction.suitability.CAPABILITIES_MISMATCH
+    ) {
+      log.error(
+        `Could not execute recipe ${recipe.name}:`,
+        `Action ${recipe.action} is either missing or invalid.`
+      );
+      await lazy.Uptake.reportRecipe(recipe, lazy.Uptake.RECIPE_INVALID_ACTION);
+    }
+  }
+
+  async finalize(options) {
+    if (this.finalized) {
+      throw new Error("ActionsManager has already been finalized");
+    }
+    this.finalized = true;
+
+    // Finalize local actions
+    for (const action of Object.values(this.localActions)) {
+      action.finalize(options);
+    }
+  }
+}
diff --git a/toolkit/components/normandy/lib/AddonRollouts.jsm b/toolkit/components/normandy/lib/AddonRollouts.jsm
new file mode 100644
index 0000000000..ffc4814155
--- /dev/null
+++ b/toolkit/components/normandy/lib/AddonRollouts.jsm
@@ -0,0 +1,231 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+"use strict";
+
+const lazy = {};
+
+ChromeUtils.defineESModuleGetters(lazy, {
+  IndexedDB: "resource://gre/modules/IndexedDB.sys.mjs",
+  TelemetryEnvironment: "resource://gre/modules/TelemetryEnvironment.sys.mjs",
+});
+ChromeUtils.defineModuleGetter(
+  lazy,
+  "TelemetryEvents",
+  "resource://normandy/lib/TelemetryEvents.jsm"
+);
+
+/**
+ * AddonRollouts store info about an active or expired addon rollouts.
+ * @typedef {object} AddonRollout
+ * @property {int} recipeId
+ *   The ID of the recipe.
+ * @property {string} slug
+ *   Unique slug of the rollout.
+ * @property {string} state
+ *   The current state of the rollout: "active", or "rolled-back".
+ *   Active means that Normandy is actively managing therollout. Rolled-back
+ *   means that the rollout was previously active, but has been rolled back for
+ *   this user.
+ * @property {int} extensionApiId
+ *   The ID used to look up the extension in Normandy's API.
+ * @property {string} addonId
+ *   The add-on ID for this particular rollout.
+ * @property {string} addonVersion
+ *   The rollout add-on version number
+ * @property {string} xpiUrl
+ *   URL that the add-on was installed from.
+ * @property {string} xpiHash
+ *   The hash of the XPI file.
+ * @property {string} xpiHashAlgorithm
+ *   The algorithm used to hash the XPI file.
+ * @property {string} enrollmentId
+ *   A random ID generated at time of enrollment. It should be included on all
+ *   telemetry related to this rollout. It should not be re-used by other
+ *   rollouts, or any other purpose. May be null on old rollouts.
+ */
+
+var EXPORTED_SYMBOLS = ["AddonRollouts"];
+const DB_NAME = "normandy-addon-rollout";
+const STORE_NAME = "addon-rollouts";
+const DB_OPTIONS = { version: 1 };
+
+/**
+ * Create a new connection to the database.
+ */
+function openDatabase() {
+  return lazy.IndexedDB.open(DB_NAME, DB_OPTIONS, db => {
+    db.createObjectStore(STORE_NAME, {
+      keyPath: "slug",
+    });
+  });
+}
+
+/**
+ * Cache the database connection so that it is shared among multiple operations.
+ */
+let databasePromise;
+function getDatabase() {
+  if (!databasePromise) {
+    databasePromise = openDatabase();
+  }
+  return databasePromise;
+}
+
+/**
+ * Get a transaction for interacting with the rollout store.
+ *
+ * @param {IDBDatabase} db
+ * @param {String} mode Either "readonly" or "readwrite"
+ *
+ * NOTE: Methods on the store returned by this function MUST be called
+ * synchronously, otherwise the transaction with the store will expire.
+ * This is why the helper takes a database as an argument; if we fetched the
+ * database in the helper directly, the helper would be async and the
+ * transaction would expire before methods on the store were called.
+ */
+function getStore(db, mode) {
+  if (!mode) {
+    throw new Error("mode is required");
+  }
+  return db.objectStore(STORE_NAME, mode);
+}
+
+const AddonRollouts = {
+  STATE_ACTIVE: "active",
+  STATE_ROLLED_BACK: "rolled-back",
+
+  async init() {
+    for (const rollout of await this.getAllActive()) {
+      lazy.TelemetryEnvironment.setExperimentActive(
+        rollout.slug,
+        rollout.state,
+        {
+          type: "normandy-addonrollout",
+        }
+      );
+    }
+  },
+
+  /** When Telemetry is disabled, clear all identifiers from the stored rollouts.  */
+  async onTelemetryDisabled() {
+    const rollouts = await this.getAll();
+    for (const rollout of rollouts) {
+      rollout.enrollmentId = lazy.TelemetryEvents.NO_ENROLLMENT_ID_MARKER;
+    }
+    await this.updateMany(rollouts);
+  },
+
+  /**
+   * Add a new rollout
+   * @param {AddonRollout} rollout
+   */
+  async add(rollout) {
+    const db = await getDatabase();
+    return getStore(db, "readwrite").add(rollout);
+  },
+
+  /**
+   * Update an existing rollout
+   * @param {AddonRollout} rollout
+   * @throws If a matching rollout does not exist.
+   */
+  async update(rollout) {
+    if (!(await this.has(rollout.slug))) {
+      throw new Error(
+        `Tried to update ${rollout.slug}, but it doesn't already exist.`
+      );
+    }
+    const db = await getDatabase();
+    return getStore(db, "readwrite").put(rollout);
+  },
+
+  /**
+   * Update many existing rollouts. More efficient than calling `update` many
+   * times in a row.
+   * @param {Array<PreferenceRollout>} rollouts
+   * @throws If any of the passed rollouts have a slug that doesn't exist in the database already.
+   */
+  async updateMany(rollouts) {
+    // Don't touch the database if there is nothing to do
+    if (!rollouts.length) {
+      return;
+    }
+
+    // Both of the below operations use .map() instead of a normal loop becaues
+    // once we get the object store, we can't let it expire by spinning the
+    // event loop. This approach queues up all the interactions with the store
+    // immediately, preventing it from expiring too soon.
+
+    const db = await getDatabase();
+    let store = await getStore(db, "readonly");
+    await Promise.all(
+      rollouts.map(async ({ slug }) => {
+        let existingRollout = await store.get(slug);
+        if (!existingRollout) {
+          throw new Error(`Tried to update ${slug}, but it doesn't exist.`);
+        }
+      })
+    );
+
+    // awaiting spun the event loop, so the store is now invalid. Get a new
+    // store. This is also a chance to get it in readwrite mode.
+    store = await getStore(db, "readwrite");
+    await Promise.all(rollouts.map(rollout => store.put(rollout)));
+  },
+
+  /**
+   * Test whether there is a rollout in storage with the given slug.
+   * @param {string} slug
+   * @returns {Promise<boolean>}
+   */
+  async has(slug) {
+    const db = await getDatabase();
+    const rollout = await getStore(db, "readonly").get(slug);
+    return !!rollout;
+  },
+
+  /**
+   * Get a rollout by slug
+   * @param {string} slug
+   */
+  async get(slug) {
+    const db = await getDatabase();
+    return getStore(db, "readonly").get(slug);
+  },
+
+  /** Get all rollouts in the database. */
+  async getAll() {
+    const db = await getDatabase();
+    return getStore(db, "readonly").getAll();
+  },
+
+  /** Get all rollouts in the "active" state. */
+  async getAllActive() {
+    const rollouts = await this.getAll();
+    return rollouts.filter(rollout => rollout.state === this.STATE_ACTIVE);
+  },
+
+  /**
+   * Test wrapper that temporarily replaces the stored rollout data with fake
+   * data for testing.
+   */
+  withTestMock() {
+    return function(testFunction) {
+      return async function inner(...args) {
+        let db = await getDatabase();
+        const oldData = await getStore(db, "readonly").getAll();
+        await getStore(db, "readwrite").clear();
+        try {
+          await testFunction(...args);
+        } finally {
+          db = await getDatabase();
+          await getStore(db, "readwrite").clear();
+          const store = getStore(db, "readwrite");
+          await Promise.all(oldData.map(d => store.add(d)));
+        }
+      };
+    };
+  },
+};
diff --git a/toolkit/components/normandy/lib/AddonStudies.jsm b/toolkit/components/normandy/lib/AddonStudies.jsm
new file mode 100644
index 0000000000..4cc94418b8
--- /dev/null
+++ b/toolkit/components/normandy/lib/AddonStudies.jsm
@@ -0,0 +1,505 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+"use strict";
+
+/**
+ * @typedef {Object} Study
+ * @property {Number} recipeId
+ *   ID of the recipe that created the study. Used as the primary key of the
+ *   study.
+ * @property {Number} slug
+ *   String code used to identify the study for use in Telemetry and logging.
+ * @property {string} userFacingName
+ *   Name of the study to show to the user
+ * @property {string} userFacingDescription
+ *   Description of the study and its intent.
+ * @property {string} branch
+ *   The branch the user is enrolled in
+ * @property {boolean} active
+ *   Is the study still running?
+ * @property {string} addonId
+ *   Add-on ID for this particular study.
+ * @property {string} addonUrl
+ *   URL that the study add-on was installed from.
+ * @property {string} addonVersion
+ *   Study add-on version number
+ * @property {int} extensionApiId
+ *   The ID used to look up the extension in Normandy's API.
+ * @property {string} extensionHash
+ *   The hash of the XPI file.
+ * @property {string} extensionHashAlgorithm
+ *   The algorithm used to hash the XPI file.
+ * @property {Date} studyStartDate
+ *   Date when the study was started.
+ * @property {Date|null} studyEndDate
+ *   Date when the study was ended.
+ * @property {Date|null} temporaryErrorDeadline
+ *   Date of when temporary errors with this experiment should no longer be
+ *   considered temporary. After this point, further errors will result in
+ *   unenrollment.
+ * @property {string} enrollmentId
+ *   A random ID generated at time of enrollment. It should be included on all
+ *   telemetry related to this study. It should not be re-used by other studies,
+ *   or any other purpose. May be null on old study.
+ */
+
+const { LogManager } = ChromeUtils.import(
+  "resource://normandy/lib/LogManager.jsm"
+);
+
+const lazy = {};
+
+ChromeUtils.defineESModuleGetters(lazy, {
+  IndexedDB: "resource://gre/modules/IndexedDB.sys.mjs",
+  TelemetryEnvironment: "resource://gre/modules/TelemetryEnvironment.sys.mjs",
+});
+ChromeUtils.defineModuleGetter(
+  lazy,
+  "AddonManager",
+  "resource://gre/modules/AddonManager.jsm"
+);
+ChromeUtils.defineModuleGetter(
+  lazy,
+  "BranchedAddonStudyAction",
+  "resource://normandy/actions/BranchedAddonStudyAction.jsm"
+);
+ChromeUtils.defineModuleGetter(
+  lazy,
+  "CleanupManager",
+  "resource://normandy/lib/CleanupManager.jsm"
+);
+ChromeUtils.defineModuleGetter(
+  lazy,
+  "TelemetryEvents",
+  "resource://normandy/lib/TelemetryEvents.jsm"
+);
+
+var EXPORTED_SYMBOLS = ["AddonStudies"];
+
+const DB_NAME = "shield";
+const STORE_NAME = "addon-studies";
+const VERSION_STORE_NAME = "addon-studies-version";
+const DB_VERSION = 2;
+const STUDY_ENDED_TOPIC = "shield-study-ended";
+const log = LogManager.getLogger("addon-studies");
+
+/**
+ * Create a new connection to the database.
+ */
+function openDatabase() {
+  return lazy.IndexedDB.open(DB_NAME, DB_VERSION, async (db, event) => {
+    if (event.oldVersion < 1) {
+      db.createObjectStore(STORE_NAME, {
+        keyPath: "recipeId",
+      });
+    }
+
+    if (event.oldVersion < 2) {
+      db.createObjectStore(VERSION_STORE_NAME);
+    }
+  });
+}
+
+/**
+ * Cache the database connection so that it is shared among multiple operations.
+ */
+let databasePromise;
+async function getDatabase() {
+  if (!databasePromise) {
+    databasePromise = openDatabase();
+  }
+  return databasePromise;
+}
+
+/**
+ * Get a transaction for interacting with the study store.
+ *
+ * @param {IDBDatabase} db
+ * @param {String} mode Either "readonly" or "readwrite"
+ *
+ * NOTE: Methods on the store returned by this function MUST be called
+ * synchronously, otherwise the transaction with the store will expire.
+ * This is why the helper takes a database as an argument; if we fetched the
+ * database in the helper directly, the helper would be async and the
+ * transaction would expire before methods on the store were called.
+ */
+function getStore(db, mode) {
+  if (!mode) {
+    throw new Error("mode is required");
+  }
+  return db.objectStore(STORE_NAME, mode);
+}
+
+var AddonStudies = {
+  /**
+   * Test wrapper that temporarily replaces the stored studies with the given
+   * ones. The original stored studies are restored upon completion.
+   *
+   * This is defined here instead of in test code since it needs to access the
+   * getDatabase, which we don't expose to avoid outside modules relying on the
+   * type of storage used for studies.
+   *
+   * @param {Array} [addonStudies=[]]
+   */
+  withStudies(addonStudies = []) {
+    return function wrapper(testFunction) {
+      return async function wrappedTestFunction(args) {
+        const oldStudies = await AddonStudies.getAll();
+        let db = await getDatabase();
+        await AddonStudies.clear();
+        const store = getStore(db, "readwrite");
+        await Promise.all(addonStudies.map(study => store.add(study)));
+
+        try {
+          await testFunction({ ...args, addonStudies });
+        } finally {
+          db = await getDatabase();
+          await AddonStudies.clear();
+          const store = getStore(db, "readwrite");
+          await Promise.all(oldStudies.map(study => store.add(study)));
+        }
+      };
+    };
+  },
+
+  async init() {
+    for (const study of await this.getAllActive()) {
+      // If an active study's add-on has been removed since we last ran, stop it.
+      const addon = await lazy.AddonManager.getAddonByID(study.addonId);
+      if (!addon) {
+        await this.markAsEnded(study, "uninstalled-sideload");
+        continue;
+      }
+
+      // Otherwise mark that study as active in Telemetry
+      lazy.TelemetryEnvironment.setExperimentActive(study.slug, study.branch, {
+        type: "normandy-addonstudy",
+        enrollmentId:
+          study.enrollmentId || lazy.TelemetryEvents.NO_ENROLLMENT_ID_MARKER,
+      });
+    }
+
+    // Listen for add-on uninstalls so we can stop the corresponding studies.
+    lazy.AddonManager.addAddonListener(this);
+    lazy.CleanupManager.addCleanupHandler(() => {
+      lazy.AddonManager.removeAddonListener(this);
+    });
+  },
+
+  /** When Telemetry is disabled, clear all identifiers from the stored studies.  */
+  async onTelemetryDisabled() {
+    const studies = await this.getAll();
+    for (const study of studies) {
+      study.enrollmentId = lazy.TelemetryEvents.NO_ENROLLMENT_ID_MARKER;
+    }
+    await this.updateMany(studies);
+  },
+
+  /**
+   * These migrations should only be called from `NormandyMigrations.jsm` and
+   * tests.
+   */
+  migrations: {
+    /**
+     * Change from "name" and "description" to "slug", "userFacingName",
+     * and "userFacingDescription".
+     */
+    async migration01AddonStudyFieldsToSlugAndUserFacingFields() {
+      const db = await getDatabase();
+      const studies = await db.objectStore(STORE_NAME, "readonly").getAll();
+
+      // If there are no studies, stop here to avoid opening the DB again.
+      if (studies.length === 0) {
+        return;
+      }
+
+      // Object stores expire after `await`, so this method accumulates a bunch of
+      // promises, and then awaits them at the end.
+      const writePromises = [];
+      const objectStore = db.objectStore(STORE_NAME, "readwrite");
+
+      for (const study of studies) {
+        // use existing name as slug
+        if (!study.slug) {
+          study.slug = study.name;
+        }
+
+        // Rename `name` and `description` as `userFacingName` and `userFacingDescription`
+        if (study.name && !study.userFacingName) {
+          study.userFacingName = study.name;
+        }
+        delete study.name;
+        if (study.description && !study.userFacingDescription) {
+          study.userFacingDescription = study.description;
+        }
+        delete study.description;
+
+        // Specify that existing recipes don't have branches
+        if (!study.branch) {
+          study.branch = AddonStudies.NO_BRANCHES_MARKER;
+        }
+
+        writePromises.push(objectStore.put(study));
+      }
+
+      await Promise.all(writePromises);
+    },
+
+    async migration02RemoveOldAddonStudyAction() {
+      const studies = await AddonStudies.getAllActive({
+        branched: AddonStudies.FILTER_NOT_BRANCHED,
+      });
+      if (!studies.length) {
+        return;
+      }
+      const action = new lazy.BranchedAddonStudyAction();
+      for (const study of studies) {
+        try {
+          await action.unenroll(
+            study.recipeId,
+            "migration-removing-unbranched-action"
+          );
+        } catch (e) {
+          log.error(
+            `Stopping add-on study ${study.slug} during migration failed: ${e}`
+          );
+        }
+      }
+    },
+  },
+
+  /**
+   * If a study add-on is uninstalled, mark the study as having ended.
+   * @param {Addon} addon
+   */
+  async onUninstalled(addon) {
+    const activeStudies = (await this.getAll()).filter(study => study.active);
+    const matchingStudy = activeStudies.find(
+      study => study.addonId === addon.id
+    );
+    if (matchingStudy) {
+      await this.markAsEnded(matchingStudy, "uninstalled");
+    }
+  },
+
+  /**
+   * Remove all stored studies.
+   */
+  async clear() {
+    const db = await getDatabase();
+    await getStore(db, "readwrite").clear();
+  },
+
+  /**
+   * Test whether there is a study in storage for the given recipe ID.
+   * @param {Number} recipeId
+   * @returns {Boolean}
+   */
+  async has(recipeId) {
+    const db = await getDatabase();
+    const study = await getStore(db, "readonly").get(recipeId);
+    return !!study;
+  },
+
+  /**
+   * Fetch a study from storage.
+   * @param {Number} recipeId
+   * @return {Study} The requested study, or null if none with that ID exist.
+   */
+  async get(recipeId) {
+    const db = await getDatabase();
+    return getStore(db, "readonly").get(recipeId);
+  },
+
+  FILTER_BRANCHED_ONLY: Symbol("FILTER_BRANCHED_ONLY"),
+  FILTER_NOT_BRANCHED: Symbol("FILTER_NOT_BRANCHED"),
+  FILTER_ALL: Symbol("FILTER_ALL"),
+
+  /**
+   * Fetch all studies in storage.
+   * @return {Array<Study>}
+   */
+  async getAll({ branched = AddonStudies.FILTER_ALL } = {}) {
+    const db = await getDatabase();
+    let results = await getStore(db, "readonly").getAll();
+
+    if (branched == AddonStudies.FILTER_BRANCHED_ONLY) {
+      results = results.filter(
+        study => study.branch != AddonStudies.NO_BRANCHES_MARKER
+      );
+    } else if (branched == AddonStudies.FILTER_NOT_BRANCHED) {
+      results = results.filter(
+        study => study.branch == AddonStudies.NO_BRANCHES_MARKER
+      );
+    }
+    return results;
+  },
+
+  /**
+   * Fetch all studies in storage.
+   * @return {Array<Study>}
+   */
+  async getAllActive(options) {
+    return (await this.getAll(options)).filter(study => study.active);
+  },
+
+  /**
+   * Add a study to storage.
+   * @return {Promise<void, Error>} Resolves when the study is stored, or rejects with an error.
+   */
+  async add(study) {
+    const db = await getDatabase();
+    return getStore(db, "readwrite").add(study);
+  },
+
+  /**
+   * Update a study in storage.
+   * @return {Promise<void, Error>} Resolves when the study is updated, or rejects with an error.
+   */
+  async update(study) {
+    const db = await getDatabase();
+    return getStore(db, "readwrite").put(study);
+  },
+
+  /**
+   * Update many existing studies. More efficient than calling `update` many
+   * times in a row.
+   * @param {Array<AddonStudy>} studies
+   * @throws If any of the passed studies have a slug that doesn't exist in the database already.
+   */
+  async updateMany(studies) {
+    // Don't touch the database if there is nothing to do
+    if (!studies.length) {
+      return;
+    }
+
+    // Both of the below operations use .map() instead of a normal loop becaues
+    // once we get the object store, we can't let it expire by spinning the
+    // event loop. This approach queues up all the interactions with the store
+    // immediately, preventing it from expiring too soon.
+
+    const db = await getDatabase();
+    let store = await getStore(db, "readonly");
+    await Promise.all(
+      studies.map(async ({ recipeId }) => {
+        let existingStudy = await store.get(recipeId);
+        if (!existingStudy) {
+          throw new Error(
+            `Tried to update addon study ${recipeId}, but it doesn't exist.`
+          );
+        }
+      })
+    );
+
+    // awaiting spun the event loop, so the store is now invalid. Get a new
+    // store. This is also a chance to get it in readwrite mode.
+    store = await getStore(db, "readwrite");
+    await Promise.all(studies.map(study => store.put(study)));
+  },
+
+  /**
+   * Remove a study from storage
+   * @param recipeId The recipeId of the study to delete
+   * @return {Promise<void, Error>} Resolves when the study is deleted, or rejects with an error.
+   */
+  async delete(recipeId) {
+    const db = await getDatabase();
+    return getStore(db, "readwrite").delete(recipeId);
+  },
+
+  /**
+   * Mark a study object as having ended. Modifies the study in-place.
+   * @param {IDBDatabase} db
+   * @param {Study} study
+   * @param {String} reason Why the study is ending.
+   */
+  async markAsEnded(study, reason = "unknown") {
+    if (reason === "unknown") {
+      log.warn(`Study ${study.slug} ending for unknown reason.`);
+    }
+
+    study.active = false;
+    study.temporaryErrorDeadline = null;
+    study.studyEndDate = new Date();
+    const db = await getDatabase();
+    await getStore(db, "readwrite").put(study);
+
+    Services.obs.notifyObservers(study, STUDY_ENDED_TOPIC, `${study.recipeId}`);
+    lazy.TelemetryEvents.sendEvent("unenroll", "addon_study", study.slug, {
+      addonId: study.addonId || AddonStudies.NO_ADDON_MARKER,
+      addonVersion: study.addonVersion || AddonStudies.NO_ADDON_MARKER,
+      reason,
+      branch: study.branch,
+      enrollmentId:
+        study.enrollmentId || lazy.TelemetryEvents.NO_ENROLLMENT_ID_MARKER,
+    });
+    lazy.TelemetryEnvironment.setExperimentInactive(study.slug);
+
+    await this.callUnenrollListeners(study.addonId, reason);
+  },
+
+  // Maps extension id -> Set(callbacks)
+  _unenrollListeners: new Map(),
+
+  /**
+   * Register a callback to be invoked when a given study ends.
+   *
+   * @param {string} id         The extension id
+   * @param {function} listener The callback
+   */
+  addUnenrollListener(id, listener) {
+    let listeners = this._unenrollListeners.get(id);
+    if (!listeners) {
+      listeners = new Set();
+      this._unenrollListeners.set(id, listeners);
+    }
+    listeners.add(listener);
+  },
+
+  /**
+   * Unregister a callback to be invoked when a given study ends.
+   *
+   * @param {string} id         The extension id
+   * @param {function} listener The callback
+   */
+  removeUnenrollListener(id, listener) {
+    let listeners = this._unenrollListeners.get(id);
+    if (listeners) {
+      listeners.delete(listener);
+    }
+  },
+
+  /**
+   * Invoke the unenroll callback (if any) for the given extension
+   *
+   * @param {string} id The extension id
+   * @param {string} reason Why the study is ending
+   *
+   * @returns {Promise} A Promise resolved after the unenroll listener
+   *                    (if any) has finished its unenroll tasks.
+   */
+  async callUnenrollListeners(id, reason) {
+    let callbacks = this._unenrollListeners.get(id) || [];
+
+    async function callCallback(cb, reason) {
+      try {
+        await cb(reason);
+      } catch (err) {
+        Cu.reportError(err);
+      }
+    }
+
+    let promises = [];
+    for (let callback of callbacks) {
+      promises.push(callCallback(callback, reason));
+    }
+
+    // Wait for all the promises to be settled. This won't throw even if some of
+    // the listeners fail.
+    await Promise.all(promises);
+  },
+};
+
+AddonStudies.NO_BRANCHES_MARKER = "__NO_BRANCHES__";
+AddonStudies.NO_ADDON_MARKER = "__NO_ADDON__";
diff --git a/toolkit/components/normandy/lib/CleanupManager.jsm b/toolkit/components/normandy/lib/CleanupManager.jsm
new file mode 100644
index 0000000000..7b3d28a51e
--- /dev/null
+++ b/toolkit/components/normandy/lib/CleanupManager.jsm
@@ -0,0 +1,53 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+"use strict";
+
+const lazy = {};
+
+ChromeUtils.defineESModuleGetters(lazy, {
+  AsyncShutdown: "resource://gre/modules/AsyncShutdown.sys.mjs",
+});
+
+var EXPORTED_SYMBOLS = ["CleanupManager"];
+
+class CleanupManagerClass {
+  constructor() {
+    this.handlers = new Set();
+    this.cleanupPromise = null;
+  }
+
+  addCleanupHandler(handler) {
+    this.handlers.add(handler);
+  }
+
+  removeCleanupHandler(handler) {
+    this.handlers.delete(handler);
+  }
+
+  async cleanup() {
+    if (this.cleanupPromise === null) {
+      this.cleanupPromise = (async () => {
+        for (const handler of this.handlers) {
+          try {
+            await handler();
+          } catch (ex) {
+            Cu.reportError(ex);
+          }
+        }
+      })();
+
+      // Block shutdown to ensure any cleanup tasks that write data are
+      // finished.
+      lazy.AsyncShutdown.profileBeforeChange.addBlocker(
+        "ShieldRecipeClient: Cleaning up",
+        this.cleanupPromise
+      );
+    }
+
+    return this.cleanupPromise;
+  }
+}
+
+var CleanupManager = new CleanupManagerClass();
diff --git a/toolkit/components/normandy/lib/ClientEnvironment.jsm b/toolkit/components/normandy/lib/ClientEnvironment.jsm
new file mode 100644
index 0000000000..eeb50e1d79
--- /dev/null
+++ b/toolkit/components/normandy/lib/ClientEnvironment.jsm
@@ -0,0 +1,147 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+"use strict";
+
+const { ClientEnvironmentBase } = ChromeUtils.import(
+  "resource://gre/modules/components-utils/ClientEnvironment.jsm"
+);
+
+const lazy = {};
+
+ChromeUtils.defineModuleGetter(
+  lazy,
+  "NormandyApi",
+  "resource://normandy/lib/NormandyApi.jsm"
+);
+ChromeUtils.defineModuleGetter(
+  lazy,
+  "PreferenceExperiments",
+  "resource://normandy/lib/PreferenceExperiments.jsm"
+);
+ChromeUtils.defineModuleGetter(
+  lazy,
+  "PreferenceRollouts",
+  "resource://normandy/lib/PreferenceRollouts.jsm"
+);
+ChromeUtils.defineModuleGetter(
+  lazy,
+  "AddonStudies",
+  "resource://normandy/lib/AddonStudies.jsm"
+);
+ChromeUtils.defineModuleGetter(
+  lazy,
+  "AddonRollouts",
+  "resource://normandy/lib/AddonRollouts.jsm"
+);
+
+var EXPORTED_SYMBOLS = ["ClientEnvironment"];
+
+// Cached API request for client attributes that are determined by the Normandy
+// service.
+let _classifyRequest = null;
+
+class ClientEnvironment extends ClientEnvironmentBase {
+  /**
+   * Fetches information about the client that is calculated on the server,
+   * like geolocation and the current time.
+   *
+   * The server request is made lazily and is cached for the entire browser
+   * session.
+   */
+  static async getClientClassification() {
+    if (!_classifyRequest) {
+      _classifyRequest = lazy.NormandyApi.classifyClient();
+    }
+    return _classifyRequest;
+  }
+
+  static clearClassifyCache() {
+    _classifyRequest = null;
+  }
+
+  /**
+   * Test wrapper that mocks the server request for classifying the client.
+   * @param  {Object}   data          Fake server data to use
+   * @param  {Function} testFunction  Test function to execute while mock data is in effect.
+   */
+  static withMockClassify(data, testFunction) {
+    return async function inner() {
+      const oldRequest = _classifyRequest;
+      _classifyRequest = Promise.resolve(data);
+      await testFunction();
+      _classifyRequest = oldRequest;
+    };
+  }
+
+  static get userId() {
+    return ClientEnvironment.randomizationId;
+  }
+
+  static get country() {
+    return (async () => {
+      const { country } = await ClientEnvironment.getClientClassification();
+      return country;
+    })();
+  }
+
+  static get request_time() {
+    return (async () => {
+      const {
+        request_time,
+      } = await ClientEnvironment.getClientClassification();
+      return request_time;
+    })();
+  }
+
+  static get experiments() {
+    return (async () => {
+      const names = { all: [], active: [], expired: [] };
+
+      for (const {
+        slug,
+        expired,
+      } of await lazy.PreferenceExperiments.getAll()) {
+        names.all.push(slug);
+        if (expired) {
+          names.expired.push(slug);
+        } else {
+          names.active.push(slug);
+        }
+      }
+
+      return names;
+    })();
+  }
+
+  static get studies() {
+    return (async () => {
+      const rv = { pref: {}, addon: {} };
+      for (const prefStudy of await lazy.PreferenceExperiments.getAll()) {
+        rv.pref[prefStudy.slug] = prefStudy;
+      }
+      for (const addonStudy of await lazy.AddonStudies.getAll()) {
+        rv.addon[addonStudy.slug] = addonStudy;
+      }
+      return rv;
+    })();
+  }
+
+  static get rollouts() {
+    return (async () => {
+      const rv = { pref: {}, addon: {} };
+      for (const prefRollout of await lazy.PreferenceRollouts.getAll()) {
+        rv.pref[prefRollout.slug] = prefRollout;
+      }
+      for (const addonRollout of await lazy.AddonRollouts.getAll()) {
+        rv.addon[addonRollout.slug] = addonRollout;
+      }
+      return rv;
+    })();
+  }
+
+  static get isFirstRun() {
+    return Services.prefs.getBoolPref("app.normandy.first_run", true);
+  }
+}
diff --git a/toolkit/components/normandy/lib/EventEmitter.jsm b/toolkit/components/normandy/lib/EventEmitter.jsm
new file mode 100644
index 0000000000..fefa101a11
--- /dev/null
+++ b/toolkit/components/normandy/lib/EventEmitter.jsm
@@ -0,0 +1,64 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+"use strict";
+
+const { LogManager } = ChromeUtils.import(
+  "resource://normandy/lib/LogManager.jsm"
+);
+
+var EXPORTED_SYMBOLS = ["EventEmitter"];
+
+const log = LogManager.getLogger("event-emitter");
+
+var EventEmitter = function() {
+  const listeners = {};
+
+  return {
+    emit(eventName, event) {
+      // Fire events async
+      Promise.resolve().then(() => {
+        if (!(eventName in listeners)) {
+          log.debug(
+            `EventEmitter: Event fired with no listeners: ${eventName}`
+          );
+          return;
+        }
+        // Clone callbacks array to avoid problems with mutation while iterating
+        const callbacks = Array.from(listeners[eventName]);
+        for (const cb of callbacks) {
+          // Clone event so it can't by modified by the handler
+          let eventToPass = event;
+          if (typeof event === "object") {
+            eventToPass = Object.assign({}, event);
+          }
+          cb(eventToPass);
+        }
+      });
+    },
+
+    on(eventName, callback) {
+      if (!(eventName in listeners)) {
+        listeners[eventName] = [];
+      }
+      listeners[eventName].push(callback);
+    },
+
+    off(eventName, callback) {
+      if (eventName in listeners) {
+        const index = listeners[eventName].indexOf(callback);
+        if (index !== -1) {
+          listeners[eventName].splice(index, 1);
+        }
+      }
+    },
+
+    once(eventName, callback) {
+      const inner = event => {
+        callback(event);
+        this.off(eventName, inner);
+      };
+      this.on(eventName, inner);
+    },
+  };
+};
diff --git a/toolkit/components/normandy/lib/Heartbeat.jsm b/toolkit/components/normandy/lib/Heartbeat.jsm
new file mode 100644
index 0000000000..56f959c24e
--- /dev/null
+++ b/toolkit/components/normandy/lib/Heartbeat.jsm
@@ -0,0 +1,399 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+"use strict";
+
+const { Preferences } = ChromeUtils.importESModule(
+  "resource://gre/modules/Preferences.sys.mjs"
+);
+const { TelemetryController } = ChromeUtils.importESModule(
+  "resource://gre/modules/TelemetryController.sys.mjs"
+);
+const { clearTimeout, setTimeout } = ChromeUtils.importESModule(
+  "resource://gre/modules/Timer.sys.mjs"
+);
+const { CleanupManager } = ChromeUtils.import(
+  "resource://normandy/lib/CleanupManager.jsm"
+);
+const { EventEmitter } = ChromeUtils.import(
+  "resource://normandy/lib/EventEmitter.jsm"
+);
+const { LogManager } = ChromeUtils.import(
+  "resource://normandy/lib/LogManager.jsm"
+);
+
+var EXPORTED_SYMBOLS = ["Heartbeat"];
+
+const PREF_SURVEY_DURATION = "browser.uitour.surveyDuration";
+const NOTIFICATION_TIME = 3000;
+const HEARTBEAT_CSS_URI = Services.io.newURI(
+  "resource://normandy/skin/shared/Heartbeat.css"
+);
+const log = LogManager.getLogger("heartbeat");
+const windowsWithInjectedCss = new WeakSet();
+let anyWindowsWithInjectedCss = false;
+
+// Add cleanup handler for CSS injected into windows by Heartbeat
+CleanupManager.addCleanupHandler(() => {
+  if (anyWindowsWithInjectedCss) {
+    for (let window of Services.wm.getEnumerator("navigator:browser")) {
+      if (windowsWithInjectedCss.has(window)) {
+        const utils = window.windowUtils;
+        utils.removeSheet(HEARTBEAT_CSS_URI, window.AGENT_SHEET);
+        windowsWithInjectedCss.delete(window);
+      }
+    }
+  }
+});
+
+/**
+ * Show the Heartbeat UI to request user feedback.
+ *
+ * @param chromeWindow
+ *        The chrome window that the heartbeat notification is displayed in.
+ * @param {Object} options Options object.
+ * @param {String} options.message
+ *        The message, or question, to display on the notification.
+ * @param {String} options.thanksMessage
+ *        The thank you message to display after user votes.
+ * @param {String} options.flowId
+ *        An identifier for this rating flow. Please note that this is only used to
+ *        identify the notification box.
+ * @param {String} [options.engagementButtonLabel=null]
+ *        The text of the engagement button to use instead of stars. If this is null
+ *        or invalid, rating stars are used.
+ * @param {String} [options.learnMoreMessage=null]
+ *        The label of the learn more link. No link will be shown if this is null.
+ * @param {String} [options.learnMoreUrl=null]
+ *        The learn more URL to open when clicking on the learn more link. No learn more
+ *        will be shown if this is an invalid URL.
+ * @param {String} [options.surveyId]
+ *        An ID for the survey, reflected in the Telemetry ping.
+ * @param {Number} [options.surveyVersion]
+ *        Survey's version number, reflected in the Telemetry ping.
+ * @param {boolean} [options.testing]
+ *        Whether this is a test survey, reflected in the Telemetry ping.
+ * @param {String} [options.postAnswerURL=null]
+ *        The url to visit after the user answers the question.
+ */
+var Heartbeat = class {
+  constructor(chromeWindow, options) {
+    if (typeof options.flowId !== "string") {
+      throw new Error(
+        `flowId must be a string, but got ${JSON.stringify(
+          options.flowId
+        )}, a ${typeof options.flowId}`
+      );
+    }
+
+    if (!options.flowId) {
+      throw new Error("flowId must not be an empty string");
+    }
+
+    if (typeof options.message !== "string") {
+      throw new Error(
+        `message must be a string, but got ${JSON.stringify(
+          options.message
+        )}, a ${typeof options.message}`
+      );
+    }
+
+    if (!options.message) {
+      throw new Error("message must not be an empty string");
+    }
+
+    if (options.postAnswerUrl) {
+      options.postAnswerUrl = new URL(options.postAnswerUrl);
+    } else {
+      options.postAnswerUrl = null;
+    }
+
+    if (options.learnMoreUrl) {
+      try {
+        options.learnMoreUrl = new URL(options.learnMoreUrl);
+      } catch (e) {
+        options.learnMoreUrl = null;
+      }
+    }
+
+    this.chromeWindow = chromeWindow;
+    this.eventEmitter = new EventEmitter();
+    this.options = options;
+    this.surveyResults = {};
+    this.buttons = [];
+
+    if (!windowsWithInjectedCss.has(chromeWindow)) {
+      windowsWithInjectedCss.add(chromeWindow);
+      const utils = chromeWindow.windowUtils;
+      utils.loadSheet(HEARTBEAT_CSS_URI, chromeWindow.AGENT_SHEET);
+      anyWindowsWithInjectedCss = true;
+    }
+
+    // so event handlers are consistent
+    this.handleWindowClosed = this.handleWindowClosed.bind(this);
+    this.close = this.close.bind(this);
+
+    // Add Learn More Link
+    if (this.options.learnMoreMessage && this.options.learnMoreUrl) {
+      this.buttons.push({
+        link: this.options.learnMoreUrl.toString(),
+        label: this.options.learnMoreMessage,
+        callback: () => {
+          this.maybeNotifyHeartbeat("LearnMore");
+          return true;
+        },
+      });
+    }
+
+    if (this.options.engagementButtonLabel) {
+      this.buttons.push({
+        label: this.options.engagementButtonLabel,
+        callback: () => {
+          // Let the consumer know user engaged.
+          this.maybeNotifyHeartbeat("Engaged");
+
+          this.userEngaged({
+            type: "button",
+            flowId: this.options.flowId,
+          });
+
+          // Return true so that the notification bar doesn't close itself since
+          // we have a thank you message to show.
+          return true;
+        },
+      });
+    }
+
+    this.notificationBox = this.chromeWindow.gNotificationBox;
+    this.notice = this.notificationBox.appendNotification(
+      "heartbeat-" + this.options.flowId,
+      {
+        label: this.options.message,
+        image: "resource://normandy/skin/shared/heartbeat-icon.svg",
+        priority: this.notificationBox.PRIORITY_SYSTEM,
+        eventCallback: eventType => {
+          if (eventType !== "removed") {
+            return;
+          }
+          this.maybeNotifyHeartbeat("NotificationClosed");
+        },
+      },
+      this.buttons
+    );
+    this.notice.classList.add("heartbeat");
+    this.notice.messageText.classList.add("heartbeat");
+
+    // Build the heartbeat stars
+    if (!this.options.engagementButtonLabel) {
+      const numStars = this.options.engagementButtonLabel ? 0 : 5;
+      this.ratingContainer = this.chromeWindow.document.createElement("span");
+      this.ratingContainer.id = "star-rating-container";
+
+      for (let i = 0; i < numStars; i++) {
+        // create a star rating element
+        const ratingElement = this.chromeWindow.document.createXULElement(
+          "toolbarbutton"
+        );
+
+        // style it
+        const starIndex = numStars - i;
+        ratingElement.className = "plain star-x";
+        ratingElement.id = "star" + starIndex;
+        ratingElement.setAttribute("data-score", starIndex);
+
+        // Add the click handler
+        ratingElement.addEventListener("click", ev => {
+          const rating = parseInt(ev.target.getAttribute("data-score"));
+          this.maybeNotifyHeartbeat("Voted", { score: rating });
+          this.userEngaged({
+            type: "stars",
+            score: rating,
+            flowId: this.options.flowId,
+          });
+        });
+
+        this.ratingContainer.appendChild(ratingElement);
+      }
+
+      this.notice.buttonContainer.append(this.ratingContainer);
+    }
+
+    // Let the consumer know the notification was shown.
+    this.maybeNotifyHeartbeat("NotificationOffered");
+    this.chromeWindow.addEventListener(
+      "SSWindowClosing",
+      this.handleWindowClosed
+    );
+
+    const surveyDuration = Preferences.get(PREF_SURVEY_DURATION, 300) * 1000;
+    this.surveyEndTimer = setTimeout(() => {
+      this.maybeNotifyHeartbeat("SurveyExpired");
+      this.close();
+    }, surveyDuration);
+
+    CleanupManager.addCleanupHandler(this.close);
+  }
+
+  maybeNotifyHeartbeat(name, data = {}) {
+    if (this.pingSent) {
+      log.warn(
+        "Heartbeat event received after Telemetry ping sent. name:",
+        name,
+        "data:",
+        data
+      );
+      return;
+    }
+
+    const timestamp = Date.now();
+    let sendPing = false;
+    let cleanup = false;
+
+    const phases = {
+      NotificationOffered: () => {
+        this.surveyResults.flowId = this.options.flowId;
+        this.surveyResults.offeredTS = timestamp;
+      },
+      LearnMore: () => {
+        if (!this.surveyResults.learnMoreTS) {
+          this.surveyResults.learnMoreTS = timestamp;
+        }
+      },
+      Engaged: () => {
+        this.surveyResults.engagedTS = timestamp;
+      },
+      Voted: () => {
+        this.surveyResults.votedTS = timestamp;
+        this.surveyResults.score = data.score;
+      },
+      SurveyExpired: () => {
+        this.surveyResults.expiredTS = timestamp;
+      },
+      NotificationClosed: () => {
+        this.surveyResults.closedTS = timestamp;
+        cleanup = true;
+        sendPing = true;
+      },
+      WindowClosed: () => {
+        this.surveyResults.windowClosedTS = timestamp;
+        cleanup = true;
+        sendPing = true;
+      },
+      default: () => {
+        log.error("Unrecognized Heartbeat event:", name);
+      },
+    };
+
+    (phases[name] || phases.default)();
+
+    data.timestamp = timestamp;
+    data.flowId = this.options.flowId;
+    this.eventEmitter.emit(name, data);
+
+    if (sendPing) {
+      // Send the ping to Telemetry
+      const payload = Object.assign({ version: 1 }, this.surveyResults);
+      for (const meta of ["surveyId", "surveyVersion", "testing"]) {
+        if (this.options.hasOwnProperty(meta)) {
+          payload[meta] = this.options[meta];
+        }
+      }
+
+      log.debug("Sending telemetry");
+      TelemetryController.submitExternalPing("heartbeat", payload, {
+        addClientId: true,
+        addEnvironment: true,
+      });
+
+      // only for testing
+      this.eventEmitter.emit("TelemetrySent", payload);
+
+      // Survey is complete, clear out the expiry timer & survey configuration
+      this.endTimerIfPresent("surveyEndTimer");
+
+      this.pingSent = true;
+      this.surveyResults = null;
+    }
+
+    if (cleanup) {
+      this.cleanup();
+    }
+  }
+
+  userEngaged(engagementParams) {
+    // Make the heartbeat icon pulse twice
+    this.notice.label = this.options.thanksMessage;
+    this.notice.messageImage.classList.remove("pulse-onshow");
+    this.notice.messageImage.classList.add("pulse-twice");
+
+    // Remove the custom contents of the notice and the buttons
+    if (this.ratingContainer) {
+      this.ratingContainer.remove();
+    }
+    for (let button of this.notice.buttonContainer.querySelectorAll("button")) {
+      button.remove();
+    }
+
+    // Open the engagement tab if we have a valid engagement URL.
+    if (this.options.postAnswerUrl) {
+      for (const key in engagementParams) {
+        this.options.postAnswerUrl.searchParams.append(
+          key,
+          engagementParams[key]
+        );
+      }
+      // Open the engagement URL in a new tab.
+      let { gBrowser } = this.chromeWindow;
+      gBrowser.selectedTab = gBrowser.addWebTab(
+        this.options.postAnswerUrl.toString(),
+        {
+          triggeringPrincipal: Services.scriptSecurityManager.createNullPrincipal(
+            {}
+          ),
+        }
+      );
+    }
+
+    this.endTimerIfPresent("surveyEndTimer");
+
+    this.engagementCloseTimer = setTimeout(
+      () => this.close(),
+      NOTIFICATION_TIME
+    );
+  }
+
+  endTimerIfPresent(timerName) {
+    if (this[timerName]) {
+      clearTimeout(this[timerName]);
+      this[timerName] = null;
+    }
+  }
+
+  handleWindowClosed() {
+    this.maybeNotifyHeartbeat("WindowClosed");
+  }
+
+  close() {
+    this.notificationBox.removeNotification(this.notice);
+  }
+
+  cleanup() {
+    // Kill the timers which might call things after we've cleaned up:
+    this.endTimerIfPresent("surveyEndTimer");
+    this.endTimerIfPresent("engagementCloseTimer");
+    // remove listeners
+    this.chromeWindow.removeEventListener(
+      "SSWindowClosing",
+      this.handleWindowClosed
+    );
+    // remove references for garbage collection
+    this.chromeWindow = null;
+    this.notificationBox = null;
+    this.notice = null;
+    this.ratingContainer = null;
+    this.eventEmitter = null;
+    // Ensure we don't re-enter and release the CleanupManager's reference to us:
+    CleanupManager.removeCleanupHandler(this.close);
+  }
+};
diff --git a/toolkit/components/normandy/lib/LogManager.jsm b/toolkit/components/normandy/lib/LogManager.jsm
new file mode 100644
index 0000000000..07420b81ae
--- /dev/null
+++ b/toolkit/components/normandy/lib/LogManager.jsm
@@ -0,0 +1,40 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+"use strict";
+
+const { Log } = ChromeUtils.importESModule(
+  "resource://gre/modules/Log.sys.mjs"
+);
+
+var EXPORTED_SYMBOLS = ["LogManager"];
+
+const ROOT_LOGGER_NAME = "app.normandy";
+let rootLogger = null;
+
+var LogManager = {
+  /**
+   * Configure the root logger for the Recipe Client. Must be called at
+   * least once before using any loggers created via getLogger.
+   * @param {Number} loggingLevel
+   *        Logging level to use as defined in Log.sys.mjs
+   */
+  configure(loggingLevel) {
+    if (!rootLogger) {
+      rootLogger = Log.repository.getLogger(ROOT_LOGGER_NAME);
+      rootLogger.addAppender(new Log.ConsoleAppender(new Log.BasicFormatter()));
+    }
+    rootLogger.level = loggingLevel;
+  },
+
+  /**
+   * Obtain a named logger with the recipe client logger as its parent.
+   * @param {String} name
+   *        Name of the logger to obtain.
+   * @return {Logger}
+   */
+  getLogger(name) {
+    return Log.repository.getLogger(`${ROOT_LOGGER_NAME}.${name}`);
+  },
+};
diff --git a/toolkit/components/normandy/lib/NormandyAddonManager.jsm b/toolkit/components/normandy/lib/NormandyAddonManager.jsm
new file mode 100644
index 0000000000..4173d2e1a9
--- /dev/null
+++ b/toolkit/components/normandy/lib/NormandyAddonManager.jsm
@@ -0,0 +1,128 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+"use strict";
+
+const { XPCOMUtils } = ChromeUtils.importESModule(
+  "resource://gre/modules/XPCOMUtils.sys.mjs"
+);
+
+const lazy = {};
+
+ChromeUtils.defineESModuleGetters(lazy, {
+  PromiseUtils: "resource://gre/modules/PromiseUtils.sys.mjs",
+});
+
+XPCOMUtils.defineLazyModuleGetters(lazy, {
+  AddonManager: "resource://gre/modules/AddonManager.jsm",
+});
+
+var EXPORTED_SYMBOLS = ["NormandyAddonManager"];
+
+const NormandyAddonManager = {
+  async downloadAndInstall({
+    createError,
+    extensionDetails,
+    applyNormandyChanges,
+    undoNormandyChanges,
+    onInstallStarted,
+    reportError,
+  }) {
+    const {
+      extension_id,
+      hash,
+      hash_algorithm,
+      version,
+      xpi,
+    } = extensionDetails;
+
+    const downloadDeferred = lazy.PromiseUtils.defer();
+    const installDeferred = lazy.PromiseUtils.defer();
+
+    const install = await lazy.AddonManager.getInstallForURL(xpi, {
+      hash: `${hash_algorithm}:${hash}`,
+      telemetryInfo: { source: "internal" },
+    });
+
+    const listener = {
+      onInstallStarted(cbInstall) {
+        const versionMatches = cbInstall.addon.version === version;
+        const idMatches = cbInstall.addon.id === extension_id;
+
+        if (!versionMatches || !idMatches) {
+          installDeferred.reject(createError("metadata-mismatch"));
+          return false; // cancel the installation, server metadata does not match downloaded add-on
+        }
+
+        if (onInstallStarted) {
+          return onInstallStarted(cbInstall, installDeferred);
+        }
+
+        return true;
+      },
+
+      onDownloadFailed() {
+        downloadDeferred.reject(
+          createError("download-failure", {
+            detail: lazy.AddonManager.errorToString(install.error),
+          })
+        );
+      },
+
+      onDownloadEnded() {
+        downloadDeferred.resolve();
+        return false; // temporarily pause installation for Normandy bookkeeping
+      },
+
+      onInstallFailed() {
+        installDeferred.reject(
+          createError("install-failure", {
+            detail: lazy.AddonManager.errorToString(install.error),
+          })
+        );
+      },
+
+      onInstallEnded() {
+        installDeferred.resolve();
+      },
+    };
+
+    install.addListener(listener);
+
+    // Download the add-on
+    try {
+      install.install();
+      await downloadDeferred.promise;
+    } catch (err) {
+      reportError(err);
+      install.removeListener(listener);
+      throw err;
+    }
+
+    // Complete any book-keeping
+    try {
+      await applyNormandyChanges(install);
+    } catch (err) {
+      reportError(err);
+      install.removeListener(listener);
+      install.cancel();
+      throw err;
+    }
+
+    // Finish paused installation
+    try {
+      install.install();
+      await installDeferred.promise;
+    } catch (err) {
+      reportError(err);
+      install.removeListener(listener);
+      await undoNormandyChanges();
+      throw err;
+    }
+
+    install.removeListener(listener);
+
+    return [install.addon.id, install.addon.version];
+  },
+};
diff --git a/toolkit/components/normandy/lib/NormandyApi.jsm b/toolkit/components/normandy/lib/NormandyApi.jsm
new file mode 100644
index 0000000000..07747f4343
--- /dev/null
+++ b/toolkit/components/normandy/lib/NormandyApi.jsm
@@ -0,0 +1,161 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+"use strict";
+
+const lazy = {};
+
+ChromeUtils.defineModuleGetter(
+  lazy,
+  "CanonicalJSON",
+  "resource://gre/modules/CanonicalJSON.jsm"
+);
+
+var EXPORTED_SYMBOLS = ["NormandyApi"];
+
+const prefs = Services.prefs.getBranch("app.normandy.");
+
+let indexPromise = null;
+
+function getChainRootIdentifier() {
+  const normandy_url = Services.prefs.getCharPref("app.normandy.api_url");
+  if (normandy_url == "https://normandy.cdn.mozilla.net/api/v1") {
+    return Ci.nsIContentSignatureVerifier.ContentSignatureProdRoot;
+  }
+  if (normandy_url.includes("stage.")) {
+    return Ci.nsIContentSignatureVerifier.ContentSignatureStageRoot;
+  }
+  if (normandy_url.includes("dev.")) {
+    return Ci.nsIContentSignatureVerifier.ContentSignatureDevRoot;
+  }
+  if (Services.env.exists("XPCSHELL_TEST_PROFILE_DIR")) {
+    return Ci.nsIX509CertDB.AppXPCShellRoot;
+  }
+  return Ci.nsIContentSignatureVerifier.ContentSignatureLocalRoot;
+}
+
+var NormandyApi = {
+  InvalidSignatureError: class InvalidSignatureError extends Error {},
+
+  clearIndexCache() {
+    indexPromise = null;
+  },
+
+  get(endpoint, data) {
+    const url = new URL(endpoint);
+    if (data) {
+      for (const key of Object.keys(data)) {
+        url.searchParams.set(key, data[key]);
+      }
+    }
+    return fetch(url.href, {
+      method: "get",
+      headers: { Accept: "application/json" },
+      credentials: "omit",
+    });
+  },
+
+  absolutify(url) {
+    if (url.startsWith("http")) {
+      return url;
+    }
+    const apiBase = prefs.getCharPref("api_url");
+    const server = new URL(apiBase).origin;
+    if (url.startsWith("/")) {
+      return server + url;
+    }
+    throw new Error("Can't use relative urls");
+  },
+
+  async getApiUrl(name) {
+    if (!indexPromise) {
+      const apiBase = new URL(prefs.getCharPref("api_url"));
+      if (!apiBase.pathname.endsWith("/")) {
+        apiBase.pathname += "/";
+      }
+      indexPromise = this.get(apiBase.toString()).then(res => res.json());
+    }
+    const index = await indexPromise;
+    if (!(name in index)) {
+      throw new Error(`API endpoint with name "${name}" not found.`);
+    }
+    const url = index[name];
+    return this.absolutify(url);
+  },
+
+  /**
+   * Verify content signature, by serializing the specified `object` as
+   * canonical JSON, and using the Normandy signer verifier to check that
+   * it matches the signature specified in `signaturePayload`.
+   *
+   * If the the signature is not valid, an error is thrown. Otherwise this
+   * function returns undefined.
+   *
+   * @param {object|String} data The object (or string) to be checked
+   * @param {object} signaturePayload The signature information
+   * @param {String} signaturePayload.x5u The certificate chain URL
+   * @param {String} signaturePayload.signature base64 signature bytes
+   * @param {String} type The object type (eg. `"recipe"`, `"action"`)
+   * @returns {Promise<undefined>} If the signature is valid, this function returns without error
+   * @throws {NormandyApi.InvalidSignatureError} if signature is invalid.
+   */
+  async verifyObjectSignature(data, signaturePayload, type) {
+    const { signature, x5u } = signaturePayload;
+    const certChainResponse = await this.get(this.absolutify(x5u));
+    const certChain = await certChainResponse.text();
+    const builtSignature = `p384ecdsa=${signature}`;
+
+    const serialized =
+      typeof data == "string" ? data : lazy.CanonicalJSON.stringify(data);
+
+    const verifier = Cc[
+      "@mozilla.org/security/contentsignatureverifier;1"
+    ].createInstance(Ci.nsIContentSignatureVerifier);
+
+    let valid;
+    try {
+      valid = await verifier.asyncVerifyContentSignature(
+        serialized,
+        builtSignature,
+        certChain,
+        "normandy.content-signature.mozilla.org",
+        getChainRootIdentifier()
+      );
+    } catch (err) {
+      throw new NormandyApi.InvalidSignatureError(
+        `${type} signature validation failed: ${err}`
+      );
+    }
+
+    if (!valid) {
+      throw new NormandyApi.InvalidSignatureError(
+        `${type} signature is not valid`
+      );
+    }
+  },
+
+  /**
+   * Fetch metadata about this client determined by the server.
+   * @return {object} Metadata specified by the server
+   */
+  async classifyClient() {
+    const classifyClientUrl = await this.getApiUrl("classify-client");
+    const response = await this.get(classifyClientUrl);
+    const clientData = await response.json();
+    clientData.request_time = new Date(clientData.request_time);
+    return clientData;
+  },
+
+  /**
+   * Fetch details for an extension from the server.
+   * @param extensionId {integer} The ID of the extension to look up
+   * @resolves {Object}
+   */
+  async fetchExtensionDetails(extensionId) {
+    const baseUrl = await this.getApiUrl("extension-list");
+    const extensionDetailsUrl = `${baseUrl}${extensionId}/`;
+    const response = await this.get(extensionDetailsUrl);
+    return response.json();
+  },
+};
diff --git a/toolkit/components/normandy/lib/NormandyUtils.jsm b/toolkit/components/normandy/lib/NormandyUtils.jsm
new file mode 100644
index 0000000000..dbee71606d
--- /dev/null
+++ b/toolkit/components/normandy/lib/NormandyUtils.jsm
@@ -0,0 +1,17 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+"use strict";
+
+var EXPORTED_SYMBOLS = ["NormandyUtils"];
+
+var NormandyUtils = {
+  generateUuid() {
+    // Generate a random UUID, convert it to a string, and slice the braces off the ends.
+    return Services.uuid
+      .generateUUID()
+      .toString()
+      .slice(1, -1);
+  },
+};
diff --git a/toolkit/components/normandy/lib/PrefUtils.jsm b/toolkit/components/normandy/lib/PrefUtils.jsm
new file mode 100644
index 0000000000..cbbf92a451
--- /dev/null
+++ b/toolkit/components/normandy/lib/PrefUtils.jsm
@@ -0,0 +1,138 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+"use strict";
+
+const { XPCOMUtils } = ChromeUtils.importESModule(
+  "resource://gre/modules/XPCOMUtils.sys.mjs"
+);
+const lazy = {};
+ChromeUtils.defineModuleGetter(
+  lazy,
+  "LogManager",
+  "resource://normandy/lib/LogManager.jsm"
+);
+
+var EXPORTED_SYMBOLS = ["PrefUtils"];
+
+XPCOMUtils.defineLazyGetter(lazy, "log", () => {
+  return lazy.LogManager.getLogger("preference-experiments");
+});
+
+const kPrefBranches = {
+  user: Services.prefs,
+  default: Services.prefs.getDefaultBranch(""),
+};
+
+var PrefUtils = {
+  /**
+   * Get a preference of any type from the named branch.
+   * @param {string} pref
+   * @param {object} [options]
+   * @param {"default"|"user"} [options.branchName="user"] One of "default" or "user"
+   * @param {string|boolean|integer|null} [options.defaultValue]
+   *   The value to return if the preference does not exist. Defaults to null.
+   */
+  getPref(pref, { branch = "user", defaultValue = null } = {}) {
+    const branchObj = kPrefBranches[branch];
+    if (!branchObj) {
+      throw new this.UnexpectedPreferenceBranch(
+        `"${branch}" is not a valid preference branch`
+      );
+    }
+    const type = branchObj.getPrefType(pref);
+
+    try {
+      switch (type) {
+        case Services.prefs.PREF_BOOL: {
+          return branchObj.getBoolPref(pref);
+        }
+        case Services.prefs.PREF_STRING: {
+          return branchObj.getStringPref(pref);
+        }
+        case Services.prefs.PREF_INT: {
+          return branchObj.getIntPref(pref);
+        }
+        case Services.prefs.PREF_INVALID: {
+          return defaultValue;
+        }
+      }
+    } catch (e) {
+      if (branch === "default" && e.result === Cr.NS_ERROR_UNEXPECTED) {
+        // There is a value for the pref on the user branch but not on the default branch. This is ok.
+        return defaultValue;
+      }
+      // Unexpected error, re-throw it
+      throw e;
+    }
+
+    // If `type` isn't any of the above, throw an error. Don't do this in a
+    // default branch of switch so that error handling is easier.
+    throw new TypeError(`Unknown preference type (${type}) for ${pref}.`);
+  },
+
+  /**
+   * Set a preference on the named branch
+   * @param {string} pref
+   * @param {string|boolean|integer|null} value The value to set.
+   * @param {object} options
+   * @param {"user"|"default"} options.branchName The branch to make the change on.
+   */
+  setPref(pref, value, { branch = "user" } = {}) {
+    if (value === null) {
+      this.clearPref(pref, { branch });
+      return;
+    }
+    const branchObj = kPrefBranches[branch];
+    if (!branchObj) {
+      throw new this.UnexpectedPreferenceBranch(
+        `"${branch}" is not a valid preference branch`
+      );
+    }
+    switch (typeof value) {
+      case "boolean": {
+        branchObj.setBoolPref(pref, value);
+        break;
+      }
+      case "string": {
+        branchObj.setStringPref(pref, value);
+        break;
+      }
+      case "number": {
+        branchObj.setIntPref(pref, value);
+        break;
+      }
+      default: {
+        throw new TypeError(
+          `Unexpected value type (${typeof value}) for ${pref}.`
+        );
+      }
+    }
+  },
+
+  /**
+   * Remove a preference from a branch. Note that default branch preferences
+   * cannot effectively be cleared. If "default" is passed for a branch, an
+   * error will be logged and nothing else will happen.
+   *
+   * @param {string} pref
+   * @param {object} options
+   * @param {"user"|"default"} options.branchName The branch to clear
+   */
+  clearPref(pref, { branch = "user" } = {}) {
+    if (branch === "user") {
+      kPrefBranches.user.clearUserPref(pref);
+    } else if (branch === "default") {
+      lazy.log.warn(
+        `Cannot reset pref ${pref} on the default branch. Pref will be cleared at next restart.`
+      );
+    } else {
+      throw new this.UnexpectedPreferenceBranch(
+        `"${branch}" is not a valid preference branch`
+      );
+    }
+  },
+
+  UnexpectedPreferenceType: class extends Error {},
+  UnexpectedPreferenceBranch: class extends Error {},
+};
diff --git a/toolkit/components/normandy/lib/PreferenceExperiments.jsm b/toolkit/components/normandy/lib/PreferenceExperiments.jsm
new file mode 100644
index 0000000000..b7de855808
--- /dev/null
+++ b/toolkit/components/normandy/lib/PreferenceExperiments.jsm
@@ -0,0 +1,1091 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+/**
+ * Preference Experiments temporarily change a preference to one of several test
+ * values for the duration of the experiment. Telemetry packets are annotated to
+ * show what experiments are active, and we use this data to measure the
+ * effectiveness of the preference change.
+ *
+ * Info on active and past experiments is stored in a JSON file in the profile
+ * folder.
+ *
+ * Active preference experiments are stopped if they aren't active on the recipe
+ * server. They also expire if Firefox isn't able to contact the recipe server
+ * after a period of time, as well as if the user modifies the preference during
+ * an active experiment.
+ */
+
+/**
+ * Experiments store info about an active or expired preference experiment.
+ * @typedef {Object} Experiment
+ * @property {string} slug
+ *   A string uniquely identifying the experiment. Used for telemetry, and other
+ *   machine-oriented use cases. Used as a display name if `userFacingName` is
+ *   null.
+ * @property {string|null} userFacingName
+ *   A user-friendly name for the experiment. Null on old-style single-preference
+ *   experiments, which do not have a userFacingName.
+ * @property {string|null} userFacingDescription
+ *   A user-friendly description of the experiment. Null on old-style
+ *   single-preference experiments, which do not have a userFacingDescription.
+ * @property {string} branch
+ *   Experiment branch that the user was matched to
+ * @property {boolean} expired
+ *   If false, the experiment is active.
+ *   ISO-formatted date string of when the experiment was last seen from the
+ *   recipe server.
+ * @property {string|null} temporaryErrorDeadline
+ *   ISO-formatted date string of when temporary errors with this experiment
+ *   should not longer be considered temporary. After this point, further errors
+ *   will result in unenrollment.
+ * @property {Object} preferences
+ *   An object consisting of all the preferences that are set by this experiment.
+ *   Keys are the name of each preference affected by this experiment. Values are
+ *   Preference Objects, about which see below.
+ * @property {string} experimentType
+ *   The type to report to Telemetry's experiment marker API.
+ * @property {string} enrollmentId
+ *   A random ID generated at time of enrollment. It should be included on all
+ *   telemetry related to this experiment. It should not be re-used by other
+ *   studies, or any other purpose. May be null on old experiments.
+ * @property {string} actionName
+ *   The action who knows about this experiment and is responsible for cleaning
+ *   it up. This should correspond to the `name` of some BaseAction subclass.
+ */
+
+/**
+ * Each Preference stores information about a preference that an
+ * experiment sets.
+ * @property {string|integer|boolean} preferenceValue
+ *   Value to change the preference to during the experiment.
+ * @property {string} preferenceType
+ *   Type of the preference value being set.
+ * @property {string|integer|boolean|undefined} previousPreferenceValue
+ *   Value of the preference prior to the experiment, or undefined if it was
+ *   unset.
+ * @property {PreferenceBranchType} preferenceBranchType
+ *   Controls how we modify the preference to affect the client.
+ *
+ *   If "default", when the experiment is active, the default value for the
+ *   preference is modified on startup of the add-on. If "user", the user value
+ *   for the preference is modified when the experiment starts, and is reset to
+ *   its original value when the experiment ends.
+ * @property {boolean} overridden
+ *   Tracks if this preference has been changed away from the experimental value.
+ */
+
+"use strict";
+
+const { AppConstants } = ChromeUtils.importESModule(
+  "resource://gre/modules/AppConstants.sys.mjs"
+);
+const { CleanupManager } = ChromeUtils.import(
+  "resource://normandy/lib/CleanupManager.jsm"
+);
+const { LogManager } = ChromeUtils.import(
+  "resource://normandy/lib/LogManager.jsm"
+);
+
+const lazy = {};
+ChromeUtils.defineESModuleGetters(lazy, {
+  JSONFile: "resource://gre/modules/JSONFile.sys.mjs",
+  TelemetryEnvironment: "resource://gre/modules/TelemetryEnvironment.sys.mjs",
+});
+ChromeUtils.defineModuleGetter(
+  lazy,
+  "TelemetryEvents",
+  "resource://normandy/lib/TelemetryEvents.jsm"
+);
+ChromeUtils.defineModuleGetter(
+  lazy,
+  "NormandyUtils",
+  "resource://normandy/lib/NormandyUtils.jsm"
+);
+ChromeUtils.defineModuleGetter(
+  lazy,
+  "PrefUtils",
+  "resource://normandy/lib/PrefUtils.jsm"
+);
+
+var EXPORTED_SYMBOLS = ["PreferenceExperiments"];
+
+const EXPERIMENT_FILE = "shield-preference-experiments.json";
+const STARTUP_EXPERIMENT_PREFS_BRANCH = "app.normandy.startupExperimentPrefs.";
+
+const MAX_EXPERIMENT_TYPE_LENGTH = 20; // enforced by TelemetryEnvironment
+const EXPERIMENT_TYPE_PREFIX = "normandy-";
+const MAX_EXPERIMENT_SUBTYPE_LENGTH =
+  MAX_EXPERIMENT_TYPE_LENGTH - EXPERIMENT_TYPE_PREFIX.length;
+
+const PREFERENCE_TYPE_MAP = {
+  boolean: Services.prefs.PREF_BOOL,
+  string: Services.prefs.PREF_STRING,
+  integer: Services.prefs.PREF_INT,
+};
+
+const UserPreferences = Services.prefs;
+const DefaultPreferences = Services.prefs.getDefaultBranch("");
+
+/**
+ * Enum storing Preference modules for each type of preference branch.
+ * @enum {Object}
+ */
+const PreferenceBranchType = {
+  user: UserPreferences,
+  default: DefaultPreferences,
+};
+
+/**
+ * Asynchronously load the JSON file that stores experiment status in the profile.
+ */
+let gStorePromise;
+function ensureStorage() {
+  if (gStorePromise === undefined) {
+    const path = PathUtils.join(
+      Services.dirsvc.get("ProfD", Ci.nsIFile).path,
+      EXPERIMENT_FILE
+    );
+    const storage = new lazy.JSONFile({ path });
+    // `storage.load()` is defined as being infallible: It won't ever throw an
+    // error. However, if there are are I/O errors, such as a corrupt, missing,
+    // or unreadable file the data loaded will be an empty object. This can
+    // happen ever after our migrations have run. If that happens, edit the
+    // storage to match our expected schema before returning it to the rest of
+    // the module.
+    gStorePromise = storage.load().then(() => {
+      if (!storage.data.experiments) {
+        storage.data = { ...storage.data, experiments: {} };
+      }
+      return storage;
+    });
+  }
+  return gStorePromise;
+}
+
+const log = LogManager.getLogger("preference-experiments");
+
+// List of active preference observers. Cleaned up on shutdown.
+let experimentObservers = new Map();
+CleanupManager.addCleanupHandler(() =>
+  PreferenceExperiments.stopAllObservers()
+);
+
+var PreferenceExperiments = {
+  /**
+   * Update the the experiment storage with changes that happened during early startup.
+   * @param {object} studyPrefsChanged Map from pref name to previous pref value
+   */
+  async recordOriginalValues(studyPrefsChanged) {
+    const store = await ensureStorage();
+
+    for (const experiment of Object.values(store.data.experiments)) {
+      for (const [prefName, prefInfo] of Object.entries(
+        experiment.preferences
+      )) {
+        if (studyPrefsChanged.hasOwnProperty(prefName)) {
+          if (experiment.expired) {
+            log.warn(
+              "Expired preference experiment changed value during startup"
+            );
+          }
+          if (prefInfo.preferenceBranch !== "default") {
+            log.warn(
+              "Non-default branch preference experiment changed value during startup"
+            );
+          }
+          prefInfo.previousPreferenceValue = studyPrefsChanged[prefName];
+        }
+      }
+    }
+
+    // not calling store.saveSoon() because if the data doesn't get
+    // written, it will get updated with fresher data next time the
+    // browser starts.
+  },
+
+  /**
+   * Set the default preference value for active experiments that use the
+   * default preference branch.
+   */
+  async init() {
+    CleanupManager.addCleanupHandler(() => this.saveStartupPrefs());
+
+    for (const experiment of await this.getAllActive()) {
+      // Check that the current value of the preference is still what we set it to
+      for (const [preferenceName, spec] of Object.entries(
+        experiment.preferences
+      )) {
+        if (
+          !spec.overridden &&
+          lazy.PrefUtils.getPref(preferenceName) !== spec.preferenceValue
+        ) {
+          // if not, record the difference
+          await this.recordPrefChange({
+            experiment,
+            preferenceName,
+            reason: "sideload",
+          });
+        }
+      }
+
+      // Notify Telemetry of experiments we're running, since they don't persist between restarts
+      lazy.TelemetryEnvironment.setExperimentActive(
+        experiment.slug,
+        experiment.branch,
+        {
+          type: EXPERIMENT_TYPE_PREFIX + experiment.experimentType,
+          enrollmentId:
+            experiment.enrollmentId ||
+            lazy.TelemetryEvents.NO_ENROLLMENT_ID_MARKER,
+        }
+      );
+
+      // Watch for changes to the experiment's preference
+      this.startObserver(experiment.slug, experiment.preferences);
+    }
+  },
+
+  /**
+   * Save in-progress, default-branch preference experiments in a sub-branch of
+   * the normandy preferences. On startup, we read these to set the
+   * experimental values.
+   *
+   * This is needed because the default branch does not persist between Firefox
+   * restarts. To compensate for that, Normandy sets the default branch to the
+   * experiment values again every startup. The values to set the preferences
+   * to are stored in user-branch preferences because preferences have minimal
+   * impact on the performance of startup.
+   */
+  async saveStartupPrefs() {
+    const prefBranch = Services.prefs.getBranch(
+      STARTUP_EXPERIMENT_PREFS_BRANCH
+    );
+    for (const pref of prefBranch.getChildList("")) {
+      prefBranch.clearUserPref(pref);
+    }
+
+    // Only store prefs to set on the default branch.
+    // Be careful not to store user branch prefs here, because this
+    // would cause the default branch to match the user branch,
+    // causing the user branch pref to get cleared.
+    const allExperiments = await this.getAllActive();
+    const defaultBranchPrefs = allExperiments
+      .flatMap(exp => Object.entries(exp.preferences))
+      .filter(
+        ([preferenceName, preferenceInfo]) =>
+          preferenceInfo.preferenceBranchType === "default"
+      );
+    for (const [preferenceName, { preferenceValue }] of defaultBranchPrefs) {
+      switch (typeof preferenceValue) {
+        case "string":
+          prefBranch.setCharPref(preferenceName, preferenceValue);
+          break;
+
+        case "number":
+          prefBranch.setIntPref(preferenceName, preferenceValue);
+          break;
+
+        case "boolean":
+          prefBranch.setBoolPref(preferenceName, preferenceValue);
+          break;
+
+        default:
+          throw new Error(`Invalid preference type ${typeof preferenceValue}`);
+      }
+    }
+  },
+
+  /**
+   * Test wrapper that temporarily replaces the stored experiment data with fake
+   * data for testing.
+   */
+  withMockExperiments(prefExperiments = []) {
+    return function wrapper(testFunction) {
+      return async function wrappedTestFunction(args) {
+        const experiments = {};
+
+        for (const exp of prefExperiments) {
+          if (exp.name) {
+            throw new Error(
+              "Preference experiments 'name' field has been replaced by 'slug' and 'userFacingName', please update."
+            );
+          }
+
+          experiments[exp.slug] = exp;
+        }
+        const data = { experiments };
+
+        const oldPromise = gStorePromise;
+        gStorePromise = Promise.resolve({
+          data,
+          saveSoon() {},
+        });
+        const oldObservers = experimentObservers;
+        experimentObservers = new Map();
+        try {
+          await testFunction({ ...args, prefExperiments });
+        } finally {
+          gStorePromise = oldPromise;
+          PreferenceExperiments.stopAllObservers();
+          experimentObservers = oldObservers;
+        }
+      };
+    };
+  },
+
+  /** When Telemetry is disabled, clear all identifiers from the stored experiments.  */
+  async onTelemetryDisabled() {
+    const store = await ensureStorage();
+    for (const experiment of Object.values(store.data.experiments)) {
+      experiment.enrollmentId = lazy.TelemetryEvents.NO_ENROLLMENT_ID_MARKER;
+    }
+    store.saveSoon();
+  },
+
+  /**
+   * Clear all stored data about active and past experiments.
+   */
+  async clearAllExperimentStorage() {
+    const store = await ensureStorage();
+    store.data = {
+      experiments: {},
+    };
+    store.saveSoon();
+  },
+
+  /**
+   * Start a new preference experiment.
+   * @param {Object} experiment
+   * @param {string} experiment.slug
+   * @param {string} experiment.actionName  The action who knows about this
+   *   experiment and is responsible for cleaning it up. This should
+   *   correspond to the name of some BaseAction subclass.
+   * @param {string} experiment.branch
+   * @param {string} experiment.preferenceName
+   * @param {string|integer|boolean} experiment.preferenceValue
+   * @param {PreferenceBranchType} experiment.preferenceBranchType
+   * @returns {Experiment} The experiment object stored in the data store
+   * @rejects {Error}
+   *   - If an experiment with the given name already exists
+   *   - if an experiment for the given preference is active
+   *   - If the given preferenceType does not match the existing stored preference
+   */
+  async start({
+    name = null, // To check if old code is still using `name` instead of `slug`, and provide a nice error message
+    slug,
+    actionName,
+    branch,
+    preferences,
+    experimentType = "exp",
+    userFacingName = null,
+    userFacingDescription = null,
+  }) {
+    if (name) {
+      throw new Error(
+        "Preference experiments 'name' field has been replaced by 'slug' and 'userFacingName', please update."
+      );
+    }
+
+    log.debug(`PreferenceExperiments.start(${slug}, ${branch})`);
+
+    const store = await ensureStorage();
+    if (slug in store.data.experiments) {
+      lazy.TelemetryEvents.sendEvent("enrollFailed", "preference_study", slug, {
+        reason: "name-conflict",
+      });
+      throw new Error(
+        `A preference experiment with the slug "${slug}" already exists.`
+      );
+    }
+
+    const activeExperiments = Object.values(store.data.experiments).filter(
+      e => !e.expired
+    );
+    const preferencesWithConflicts = Object.keys(preferences).filter(
+      preferenceName => {
+        return activeExperiments.some(e =>
+          e.preferences.hasOwnProperty(preferenceName)
+        );
+      }
+    );
+
+    if (preferencesWithConflicts.length) {
+      lazy.TelemetryEvents.sendEvent("enrollFailed", "preference_study", slug, {
+        reason: "pref-conflict",
+      });
+      throw new Error(
+        `Another preference experiment for the pref "${preferencesWithConflicts[0]}" is currently active.`
+      );
+    }
+
+    if (experimentType.length > MAX_EXPERIMENT_SUBTYPE_LENGTH) {
+      lazy.TelemetryEvents.sendEvent("enrollFailed", "preference_study", slug, {
+        reason: "experiment-type-too-long",
+      });
+      throw new Error(
+        `experimentType must be less than ${MAX_EXPERIMENT_SUBTYPE_LENGTH} characters. ` +
+          `"${experimentType}" is ${experimentType.length} long.`
+      );
+    }
+
+    // Sanity check each preference
+    for (const [preferenceName, preferenceInfo] of Object.entries(
+      preferences
+    )) {
+      // Ensure preferenceBranchType is set, using the default from
+      // the schema. This also modifies the preferenceInfo for use in
+      // the rest of the function.
+      preferenceInfo.preferenceBranchType =
+        preferenceInfo.preferenceBranchType || "default";
+      const { preferenceBranchType, preferenceType } = preferenceInfo;
+      if (
+        !(preferenceBranchType === "user" || preferenceBranchType === "default")
+      ) {
+        lazy.TelemetryEvents.sendEvent(
+          "enrollFailed",
+          "preference_study",
+          slug,
+          {
+            reason: "invalid-branch",
+            prefBranch: preferenceBranchType.slice(0, 80),
+          }
+        );
+        throw new Error(
+          `Invalid value for preferenceBranchType: ${preferenceBranchType}`
+        );
+      }
+
+      const prevPrefType = Services.prefs.getPrefType(preferenceName);
+      const givenPrefType = PREFERENCE_TYPE_MAP[preferenceType];
+
+      if (!preferenceType || !givenPrefType) {
+        lazy.TelemetryEvents.sendEvent(
+          "enrollFailed",
+          "preference_study",
+          slug,
+          {
+            reason: "invalid-type",
+          }
+        );
+        throw new Error(
+          `Invalid preferenceType provided (given "${preferenceType}")`
+        );
+      }
+
+      if (
+        prevPrefType !== Services.prefs.PREF_INVALID &&
+        prevPrefType !== givenPrefType
+      ) {
+        lazy.TelemetryEvents.sendEvent(
+          "enrollFailed",
+          "preference_study",
+          slug,
+          {
+            reason: "invalid-type",
+          }
+        );
+        throw new Error(
+          `Previous preference value is of type "${prevPrefType}", but was given ` +
+            `"${givenPrefType}" (${preferenceType})`
+        );
+      }
+
+      preferenceInfo.previousPreferenceValue = lazy.PrefUtils.getPref(
+        preferenceName,
+        { branch: preferenceBranchType }
+      );
+    }
+
+    const alreadyOverriddenPrefs = new Set();
+    for (const [preferenceName, preferenceInfo] of Object.entries(
+      preferences
+    )) {
+      const { preferenceValue, preferenceBranchType } = preferenceInfo;
+
+      if (preferenceBranchType === "default") {
+        // Only set the pref if there is no user-branch value, because
+        // changing the default-branch value to the same value as the
+        // user-branch will effectively delete the user value.
+        if (Services.prefs.prefHasUserValue(preferenceName)) {
+          alreadyOverriddenPrefs.add(preferenceName);
+        } else {
+          lazy.PrefUtils.setPref(preferenceName, preferenceValue, {
+            branch: preferenceBranchType,
+          });
+        }
+      } else if (preferenceBranchType === "user") {
+        // The original value was already backed up above.
+        lazy.PrefUtils.setPref(preferenceName, preferenceValue, {
+          branch: preferenceBranchType,
+        });
+      } else {
+        log.error(`Unexpected preference branch type ${preferenceBranchType}`);
+      }
+    }
+    PreferenceExperiments.startObserver(slug, preferences);
+
+    const enrollmentId = lazy.NormandyUtils.generateUuid();
+
+    /** @type {Experiment} */
+    const experiment = {
+      slug,
+      actionName,
+      branch,
+      expired: false,
+      lastSeen: new Date().toJSON(),
+      preferences,
+      experimentType,
+      userFacingName,
+      userFacingDescription,
+      enrollmentId,
+    };
+
+    store.data.experiments[slug] = experiment;
+    store.saveSoon();
+
+    // Record telemetry that the experiment started
+    lazy.TelemetryEnvironment.setExperimentActive(slug, branch, {
+      type: EXPERIMENT_TYPE_PREFIX + experimentType,
+      enrollmentId:
+        enrollmentId || lazy.TelemetryEvents.NO_ENROLLMENT_ID_MARKER,
+    });
+    lazy.TelemetryEvents.sendEvent("enroll", "preference_study", slug, {
+      experimentType,
+      branch,
+      enrollmentId:
+        enrollmentId || lazy.TelemetryEvents.NO_ENROLLMENT_ID_MARKER,
+    });
+
+    // Send events for any default branch preferences set that already had user
+    // values overriding them.
+    for (const preferenceName of alreadyOverriddenPrefs) {
+      await this.recordPrefChange({
+        experiment,
+        preferenceName,
+        reason: "onEnroll",
+      });
+    }
+    await this.saveStartupPrefs();
+
+    return experiment;
+  },
+
+  /**
+   * Register a preference observer that stops an experiment when the user
+   * modifies the preference.
+   * @param {string} experimentSlug
+   * @param {string} preferenceName
+   * @param {string|integer|boolean} preferenceValue
+   * @throws {Error}
+   *   If an observer for the experiment is already active.
+   */
+  startObserver(experimentSlug, preferences) {
+    log.debug(`PreferenceExperiments.startObserver(${experimentSlug})`);
+
+    if (experimentObservers.has(experimentSlug)) {
+      throw new Error(
+        `An observer for the preference experiment ${experimentSlug} is already active.`
+      );
+    }
+
+    const observerInfo = {
+      preferences,
+      observe(aSubject, aTopic, preferenceName) {
+        const prefInfo = preferences[preferenceName];
+        // if `preferenceName` is one of the experiment prefs but with more on
+        // the end (ie, foo.bar vs foo.bar.baz) then this can be triggered for
+        // changes we don't care about. Check for that.
+        if (!prefInfo) {
+          return;
+        }
+        const originalValue = prefInfo.preferenceValue;
+        const newValue = lazy.PrefUtils.getPref(preferenceName);
+        if (newValue !== originalValue) {
+          PreferenceExperiments.recordPrefChange({
+            experimentSlug,
+            preferenceName,
+            reason: "observer",
+          });
+          Services.prefs.removeObserver(preferenceName, observerInfo);
+        }
+      },
+    };
+    experimentObservers.set(experimentSlug, observerInfo);
+    for (const [preferenceName, spec] of Object.entries(preferences)) {
+      if (!spec.overridden) {
+        Services.prefs.addObserver(preferenceName, observerInfo);
+      }
+    }
+  },
+
+  /**
+   * Check if a preference observer is active for an experiment.
+   * @param {string} experimentSlug
+   * @return {Boolean}
+   */
+  hasObserver(experimentSlug) {
+    log.debug(`PreferenceExperiments.hasObserver(${experimentSlug})`);
+    return experimentObservers.has(experimentSlug);
+  },
+
+  /**
+   * Disable a preference observer for an experiment.
+   * @param {string} experimentSlug
+   * @throws {Error}
+   *   If there is no active observer for the experiment.
+   */
+  stopObserver(experimentSlug) {
+    log.debug(`PreferenceExperiments.stopObserver(${experimentSlug})`);
+
+    if (!experimentObservers.has(experimentSlug)) {
+      throw new Error(
+        `No observer for the preference experiment ${experimentSlug} found.`
+      );
+    }
+
+    const observer = experimentObservers.get(experimentSlug);
+    for (const preferenceName of Object.keys(observer.preferences)) {
+      Services.prefs.removeObserver(preferenceName, observer);
+    }
+    experimentObservers.delete(experimentSlug);
+  },
+
+  /**
+   * Disable all currently-active preference observers for experiments.
+   */
+  stopAllObservers() {
+    log.debug("PreferenceExperiments.stopAllObservers()");
+    for (const observer of experimentObservers.values()) {
+      for (const preferenceName of Object.keys(observer.preferences)) {
+        Services.prefs.removeObserver(preferenceName, observer);
+      }
+    }
+    experimentObservers.clear();
+  },
+
+  /**
+   * Update the timestamp storing when Normandy last sent a recipe for the
+   * experiment.
+   * @param {string} experimentSlug
+   * @rejects {Error}
+   *   If there is no stored experiment with the given slug.
+   */
+  async markLastSeen(experimentSlug) {
+    log.debug(`PreferenceExperiments.markLastSeen(${experimentSlug})`);
+
+    const store = await ensureStorage();
+    if (!(experimentSlug in store.data.experiments)) {
+      throw new Error(
+        `Could not find a preference experiment with the slug "${experimentSlug}"`
+      );
+    }
+
+    store.data.experiments[experimentSlug].lastSeen = new Date().toJSON();
+    store.saveSoon();
+  },
+
+  /**
+   * Called when an experimental pref has changed away from its experimental
+   * value for the first time.
+   *
+   * One of `experiment` or `slug` must be passed.
+   *
+   * @param {object} options
+   * @param {Experiment} [options.experiment]
+   *   The experiment that had a pref change. If this is passed, slug is ignored.
+   * @param {string} [options.slug]
+   *   The slug of the experiment that had a pref change. This will be used to
+   *   fetch an experiment if none was passed.
+   * @param {string} options.preferenceName The preference changed.
+   * @param {string} options.reason The reason the preference change was detected.
+   */
+  async recordPrefChange({
+    experiment = null,
+    experimentSlug = null,
+    preferenceName,
+    reason,
+  }) {
+    if (!experiment) {
+      experiment = await PreferenceExperiments.get(experimentSlug);
+    }
+    let preferenceSpecification = experiment.preferences[preferenceName];
+    if (!preferenceSpecification) {
+      throw new PreferenceExperiments.InvalidPreferenceName(
+        `Preference "${preferenceName}" is not a part of experiment "${experimentSlug}"`
+      );
+    }
+
+    preferenceSpecification.overridden = true;
+    await this.update(experiment);
+
+    lazy.TelemetryEvents.sendEvent(
+      "expPrefChanged",
+      "preference_study",
+      experiment.slug,
+      {
+        preferenceName,
+        reason,
+        enrollmentId:
+          experiment.enrollmentId ||
+          lazy.TelemetryEvents.NO_ENROLLMENT_ID_MARKER,
+      }
+    );
+  },
+
+  /**
+   * Stop an active experiment, deactivate preference watchers, and optionally
+   * reset the associated preference to its previous value.
+   * @param {string} experimentSlug
+   * @param {Object} options
+   * @param {boolean} [options.resetValue = true]
+   *   If true, reset the preference to its original value prior to
+   *   the experiment. Optional, defaults to true.
+   * @param {String} [options.reason = "unknown"]
+   *   Reason that the experiment is ending. Optional, defaults to
+   *   "unknown".
+   * @rejects {Error}
+   *   If there is no stored experiment with the given slug, or if the
+   *   experiment has already expired.
+   */
+  async stop(
+    experimentSlug,
+    { resetValue = true, reason = "unknown", changedPref, caller } = {}
+  ) {
+    log.debug(
+      `PreferenceExperiments.stop(${experimentSlug}, {resetValue: ${resetValue}, reason: ${reason}, changedPref: ${changedPref}, caller: ${caller}})`
+    );
+    if (reason === "unknown") {
+      log.warn(`experiment ${experimentSlug} ending for unknown reason`);
+    }
+
+    const store = await ensureStorage();
+    if (!(experimentSlug in store.data.experiments)) {
+      lazy.TelemetryEvents.sendEvent(
+        "unenrollFailed",
+        "preference_study",
+        experimentSlug,
+        {
+          reason: "does-not-exist",
+          originalReason: reason,
+          ...(changedPref ? { changedPref } : {}),
+        }
+      );
+      throw new Error(
+        `Could not find a preference experiment with the slug "${experimentSlug}"`
+      );
+    }
+
+    const experiment = store.data.experiments[experimentSlug];
+    if (experiment.expired) {
+      const extra = {
+        reason: "already-unenrolled",
+        originalReason: reason,
+        enrollmentId:
+          experiment.enrollmentId ||
+          lazy.TelemetryEvents.NO_ENROLLMENT_ID_MARKER,
+      };
+      if (changedPref) {
+        extra.changedPref = changedPref;
+      }
+      if (caller && AppConstants.NIGHTLY_BUILD) {
+        extra.caller = caller;
+      }
+      lazy.TelemetryEvents.sendEvent(
+        "unenrollFailed",
+        "preference_study",
+        experimentSlug,
+        extra
+      );
+      throw new Error(
+        `Cannot stop preference experiment "${experimentSlug}" because it is already expired`
+      );
+    }
+
+    if (PreferenceExperiments.hasObserver(experimentSlug)) {
+      PreferenceExperiments.stopObserver(experimentSlug);
+    }
+
+    if (resetValue) {
+      for (const [
+        preferenceName,
+        { previousPreferenceValue, preferenceBranchType, overridden },
+      ] of Object.entries(experiment.preferences)) {
+        // Overridden user prefs should keep their new value, even if that value
+        // is the same as the experimental value, since it is the value the user
+        // chose.
+        if (overridden && preferenceBranchType === "user") {
+          continue;
+        }
+
+        const preferences = PreferenceBranchType[preferenceBranchType];
+
+        if (previousPreferenceValue !== null) {
+          lazy.PrefUtils.setPref(preferenceName, previousPreferenceValue, {
+            branch: preferenceBranchType,
+          });
+        } else if (preferenceBranchType === "user") {
+          // Remove the "user set" value (which Shield set), but leave the default intact.
+          preferences.clearUserPref(preferenceName);
+        } else {
+          log.warn(
+            `Can't revert pref ${preferenceName} for experiment ${experimentSlug} ` +
+              `because it had no default value. ` +
+              `Preference will be reset at the next restart.`
+          );
+          // It would seem that Services.prefs.deleteBranch() could be used for
+          // this, but in Normandy's case it does not work. See bug 1502410.
+        }
+      }
+    }
+
+    experiment.expired = true;
+    if (experiment.temporaryErrorDeadline) {
+      experiment.temporaryErrorDeadline = null;
+    }
+    await store.saveSoon();
+
+    lazy.TelemetryEnvironment.setExperimentInactive(experimentSlug);
+    lazy.TelemetryEvents.sendEvent(
+      "unenroll",
+      "preference_study",
+      experimentSlug,
+      {
+        didResetValue: resetValue ? "true" : "false",
+        branch: experiment.branch,
+        reason,
+        enrollmentId:
+          experiment.enrollmentId ||
+          lazy.TelemetryEvents.NO_ENROLLMENT_ID_MARKER,
+        ...(changedPref ? { changedPref } : {}),
+      }
+    );
+    await this.saveStartupPrefs();
+    Services.obs.notifyObservers(
+      null,
+      "normandy:preference-experiment:stopped",
+      experimentSlug
+    );
+  },
+
+  /**
+   * Clone an experiment using knowledge of its structure to avoid
+   * having to serialize/deserialize it.
+   *
+   * We do this in places where return experiments so clients can't
+   * accidentally mutate our data underneath us.
+   */
+  _cloneExperiment(experiment) {
+    return {
+      ...experiment,
+      preferences: {
+        ...experiment.preferences,
+      },
+    };
+  },
+
+  /**
+   * Get the experiment object for the experiment.
+   * @param {string} experimentSlug
+   * @resolves {Experiment}
+   * @rejects {Error}
+   *   If no preference experiment exists with the given slug.
+   */
+  async get(experimentSlug) {
+    log.debug(`PreferenceExperiments.get(${experimentSlug})`);
+    const store = await ensureStorage();
+    if (!(experimentSlug in store.data.experiments)) {
+      throw new PreferenceExperiments.NotFoundError(
+        `Could not find a preference experiment with the slug "${experimentSlug}"`
+      );
+    }
+
+    return this._cloneExperiment(store.data.experiments[experimentSlug]);
+  },
+
+  /**
+   * Get a list of all stored experiment objects.
+   * @resolves {Experiment[]}
+   */
+  async getAll() {
+    const store = await ensureStorage();
+    return Object.values(store.data.experiments).map(experiment =>
+      this._cloneExperiment(experiment)
+    );
+  },
+
+  /**
+   * Get a list of experiment objects for all active experiments.
+   * @resolves {Experiment[]}
+   */
+  async getAllActive() {
+    const store = await ensureStorage();
+    return Object.values(store.data.experiments)
+      .filter(e => !e.expired)
+      .map(e => this._cloneExperiment(e));
+  },
+
+  /**
+   * Check if an experiment exists with the given slug.
+   * @param {string} experimentSlug
+   * @resolves {boolean} True if the experiment exists, false if it doesn't.
+   */
+  async has(experimentSlug) {
+    log.debug(`PreferenceExperiments.has(${experimentSlug})`);
+    const store = await ensureStorage();
+    return experimentSlug in store.data.experiments;
+  },
+
+  /**
+   * Update an experiment in the data store. If an experiment with the given
+   * slug is not already in the store, an error will be thrown.
+   *
+   * @param experiment {Experiment} The experiment to update
+   * @param experiment.slug {String} The experiment must have a slug
+   */
+  async update(experiment) {
+    const store = await ensureStorage();
+
+    if (!(experiment.slug in store.data.experiments)) {
+      throw new Error(
+        `Could not update a preference experiment with the slug "${experiment.slug}"`
+      );
+    }
+
+    store.data.experiments[experiment.slug] = experiment;
+    store.saveSoon();
+  },
+
+  NotFoundError: class extends Error {},
+  InvalidPreferenceName: class extends Error {},
+
+  /**
+   * These migrations should only be called from `NormandyMigrations.jsm` and tests.
+   */
+  migrations: {
+    /** Move experiments into a specific key. */
+    async migration01MoveExperiments(storage = null) {
+      if (storage === null) {
+        storage = await ensureStorage();
+      }
+      if (Object.hasOwnProperty.call(storage.data, "experiments")) {
+        return;
+      }
+      storage.data = {
+        experiments: storage.data,
+      };
+      delete storage.data.experiments.__version;
+      storage.saveSoon();
+    },
+
+    /** Migrate storage.data to multi-preference format */
+    async migration02MultiPreference(storage = null) {
+      if (storage === null) {
+        storage = await ensureStorage();
+      }
+
+      const oldExperiments = storage.data.experiments;
+      const v2Experiments = {};
+
+      for (let [expName, oldExperiment] of Object.entries(oldExperiments)) {
+        if (expName == "__version") {
+          // A stray "__version" entry snuck in, likely from old migrations.
+          // Ignore it and continue. It won't be propagated to future
+          // migrations, since `v2Experiments` won't have it.
+          continue;
+        }
+        if (oldExperiment.preferences) {
+          // experiment is already migrated
+          v2Experiments[expName] = oldExperiment;
+          continue;
+        }
+        v2Experiments[expName] = {
+          name: oldExperiment.name,
+          branch: oldExperiment.branch,
+          expired: oldExperiment.expired,
+          lastSeen: oldExperiment.lastSeen,
+          preferences: {
+            [oldExperiment.preferenceName]: {
+              preferenceBranchType: oldExperiment.preferenceBranchType,
+              preferenceType: oldExperiment.preferenceType,
+              preferenceValue: oldExperiment.preferenceValue,
+              previousPreferenceValue: oldExperiment.previousPreferenceValue,
+            },
+          },
+          experimentType: oldExperiment.experimentType,
+        };
+      }
+      storage.data.experiments = v2Experiments;
+      storage.saveSoon();
+    },
+
+    /** Add "actionName" field for experiments that don't have it. */
+    async migration03AddActionName(storage = null) {
+      if (storage === null) {
+        storage = await ensureStorage();
+      }
+
+      for (const experiment of Object.values(storage.data.experiments)) {
+        if (!experiment.actionName) {
+          // Assume SinglePreferenceExperimentAction because as of this
+          // writing, no multi-pref experiment recipe has launched.
+          experiment.actionName = "SinglePreferenceExperimentAction";
+        }
+      }
+      storage.saveSoon();
+    },
+
+    async migration04RenameNameToSlug(storage = null) {
+      if (!storage) {
+        storage = await ensureStorage();
+      }
+      // Rename "name" to "slug" to match the intended purpose of the field.
+      for (const experiment of Object.values(storage.data.experiments)) {
+        if (experiment.name && !experiment.slug) {
+          experiment.slug = experiment.name;
+          delete experiment.name;
+        }
+      }
+      storage.saveSoon();
+    },
+
+    async migration05RemoveOldAction() {
+      const experiments = await PreferenceExperiments.getAllActive();
+      for (const experiment of experiments) {
+        if (experiment.actionName == "SinglePreferenceExperimentAction") {
+          try {
+            await PreferenceExperiments.stop(experiment.slug, {
+              resetValue: true,
+              reason: "migration-removing-single-pref-action",
+              caller: "migration05RemoveOldAction",
+            });
+          } catch (e) {
+            log.error(
+              `Stopping preference experiment ${experiment.slug} during migration failed: ${e}`
+            );
+          }
+        }
+      }
+    },
+
+    async migration06TrackOverriddenPrefs(storage = null) {
+      if (!storage) {
+        storage = await ensureStorage();
+      }
+      for (const experiment of Object.values(storage.data.experiments)) {
+        for (const [preferenceName, specification] of Object.entries(
+          experiment.preferences
+        )) {
+          if (specification.overridden !== undefined) {
+            continue;
+          }
+          specification.overridden =
+            lazy.PrefUtils.getPref(preferenceName) !==
+            specification.preferenceValue;
+        }
+      }
+      storage.saveSoon();
+    },
+  },
+};
diff --git a/toolkit/components/normandy/lib/PreferenceRollouts.jsm b/toolkit/components/normandy/lib/PreferenceRollouts.jsm
new file mode 100644
index 0000000000..05ea83cf58
--- /dev/null
+++ b/toolkit/components/normandy/lib/PreferenceRollouts.jsm
@@ -0,0 +1,366 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+"use strict";
+
+const { LogManager } = ChromeUtils.import(
+  "resource://normandy/lib/LogManager.jsm"
+);
+const lazy = {};
+ChromeUtils.defineESModuleGetters(lazy, {
+  IndexedDB: "resource://gre/modules/IndexedDB.sys.mjs",
+  TelemetryEnvironment: "resource://gre/modules/TelemetryEnvironment.sys.mjs",
+});
+ChromeUtils.defineModuleGetter(
+  lazy,
+  "CleanupManager",
+  "resource://normandy/lib/CleanupManager.jsm"
+);
+ChromeUtils.defineModuleGetter(
+  lazy,
+  "PrefUtils",
+  "resource://normandy/lib/PrefUtils.jsm"
+);
+ChromeUtils.defineModuleGetter(
+  lazy,
+  "TelemetryEvents",
+  "resource://normandy/lib/TelemetryEvents.jsm"
+);
+
+const log = LogManager.getLogger("recipe-runner");
+
+/**
+ * PreferenceRollouts store info about an active or expired preference rollout.
+ * @typedef {object} PreferenceRollout
+ * @property {string} slug
+ *   Unique slug of the experiment
+ * @property {string} state
+ *   The current state of the rollout: "active", "rolled-back", "graduated".
+ *   Active means that Normandy is actively managing therollout. Rolled-back
+ *   means that the rollout was previously active, but has been rolled back for
+ *   this user. Graduated means that the built-in default now matches the
+ *   rollout value, and so Normandy is no longer managing the preference.
+ * @property {Array<PreferenceSpec>} preferences
+ *   An array of preferences specifications involved in the rollout.
+ * @property {string} enrollmentId
+ *   A random ID generated at time of enrollment. It should be included on all
+ *   telemetry related to this rollout. It should not be re-used by other
+ *   rollouts, or any other purpose. May be null on old rollouts.
+ */
+
+/**
+ * PreferenceSpec describe how a preference should change during a rollout.
+ * @typedef {object} PreferenceSpec
+ * @property {string} preferenceName
+ *   The preference to modify.
+ * @property {string} preferenceType
+ *   Type of the preference being set.
+ * @property {string|integer|boolean} value
+ *   The value to change the preference to.
+ * @property {string|integer|boolean} previousValue
+ *   The value the preference would have on the default branch if this rollout
+ *   were not active.
+ */
+
+var EXPORTED_SYMBOLS = ["PreferenceRollouts"];
+const STARTUP_PREFS_BRANCH = "app.normandy.startupRolloutPrefs.";
+const DB_NAME = "normandy-preference-rollout";
+const STORE_NAME = "preference-rollouts";
+const DB_VERSION = 1;
+
+/**
+ * Create a new connection to the database.
+ */
+function openDatabase() {
+  return lazy.IndexedDB.open(DB_NAME, DB_VERSION, db => {
+    db.createObjectStore(STORE_NAME, {
+      keyPath: "slug",
+    });
+  });
+}
+
+/**
+ * Cache the database connection so that it is shared among multiple operations.
+ */
+let databasePromise;
+function getDatabase() {
+  if (!databasePromise) {
+    databasePromise = openDatabase();
+  }
+  return databasePromise;
+}
+
+/**
+ * Get a transaction for interacting with the rollout store.
+ *
+ * @param {IDBDatabase} db
+ * @param {String} mode Either "readonly" or "readwrite"
+ *
+ * NOTE: Methods on the store returned by this function MUST be called
+ * synchronously, otherwise the transaction with the store will expire.
+ * This is why the helper takes a database as an argument; if we fetched the
+ * database in the helper directly, the helper would be async and the
+ * transaction would expire before methods on the store were called.
+ */
+function getStore(db, mode) {
+  if (!mode) {
+    throw new Error("mode is required");
+  }
+  return db.objectStore(STORE_NAME, mode);
+}
+
+var PreferenceRollouts = {
+  STATE_ACTIVE: "active",
+  STATE_ROLLED_BACK: "rolled-back",
+  STATE_GRADUATED: "graduated",
+
+  // A set of rollout slugs that are obsolete based on the code in this build of
+  // Firefox. This may include things like the preference no longer being
+  // applicable, or the feature changing in such a way that Normandy's automatic
+  // graduation system cannot detect that the rollout should hand off to the
+  // built-in code.
+  GRADUATION_SET: new Set([
+    "pref-webrender-intel-rollout-70-release",
+    "bug-1703186-rollout-http3-support-release-88-89",
+    "rollout-doh-nightly-rollout-to-all-us-desktop-users-nightly-74-80-bug-1613481",
+    "rollout-doh-beta-rollout-to-all-us-desktop-users-v2-beta-74-80-bug-1613489",
+    "rollout-doh-us-staged-rollout-to-all-us-desktop-users-release-73-77-bug-1586331",
+    "bug-1648229-rollout-comcast-steering-rollout-release-78-80",
+    "bug-1732206-rollout-fission-release-rollout-release-94-95",
+    "bug-1745237-rollout-fission-beta-96-97-rollout-beta-96-97",
+    "bug-1750601-rollout-doh-steering-in-canada-staggered-starting-for-release-97-98",
+    "bug-1758988-rollout-doh-enablment-to-new-countries-staggered-st-release-98-100",
+    "bug-1758818-rollout-enabling-doh-in-new-countries-staggered-sta-release-98-100",
+  ]),
+
+  /**
+   * Update the rollout database with changes that happened during early startup.
+   * @param {object} rolloutPrefsChanged Map from pref name to previous pref value
+   */
+  async recordOriginalValues(originalPreferences) {
+    for (const rollout of await this.getAllActive()) {
+      let shouldSaveRollout = false;
+
+      // Count the number of preferences in this rollout that are now redundant.
+      let prefMatchingDefaultCount = 0;
+
+      for (const prefSpec of rollout.preferences) {
+        const builtInDefault = originalPreferences[prefSpec.preferenceName];
+        if (prefSpec.value === builtInDefault) {
+          prefMatchingDefaultCount++;
+        }
+        // Store the current built-in default. That way, if the preference is
+        // rolled back during the current session (ie, until the browser is
+        // shut down), the correct value will be used.
+        if (prefSpec.previousValue !== builtInDefault) {
+          prefSpec.previousValue = builtInDefault;
+          shouldSaveRollout = true;
+        }
+      }
+
+      if (prefMatchingDefaultCount === rollout.preferences.length) {
+        // Firefox's builtin defaults have caught up to the rollout, making all
+        // of the rollout's changes redundant, so graduate the rollout.
+        await this.graduate(rollout, "all-prefs-match");
+        // `this.graduate` writes the rollout to the db, so we don't need to do it anymore.
+        shouldSaveRollout = false;
+      }
+
+      if (shouldSaveRollout) {
+        const db = await getDatabase();
+        await getStore(db, "readwrite").put(rollout);
+      }
+    }
+  },
+
+  async init() {
+    lazy.CleanupManager.addCleanupHandler(() => this.saveStartupPrefs());
+
+    for (const rollout of await this.getAllActive()) {
+      if (this.GRADUATION_SET.has(rollout.slug)) {
+        await this.graduate(rollout, "in-graduation-set");
+        continue;
+      }
+      lazy.TelemetryEnvironment.setExperimentActive(
+        rollout.slug,
+        rollout.state,
+        {
+          type: "normandy-prefrollout",
+          enrollmentId:
+            rollout.enrollmentId ||
+            lazy.TelemetryEvents.NO_ENROLLMENT_ID_MARKER,
+        }
+      );
+    }
+  },
+
+  /** When Telemetry is disabled, clear all identifiers from the stored rollouts.  */
+  async onTelemetryDisabled() {
+    const rollouts = await this.getAll();
+    for (const rollout of rollouts) {
+      rollout.enrollmentId = lazy.TelemetryEvents.NO_ENROLLMENT_ID_MARKER;
+    }
+    await this.updateMany(rollouts);
+  },
+
+  /**
+   * Test wrapper that temporarily replaces the stored rollout data with fake
+   * data for testing.
+   */
+  withTestMock({
+    graduationSet = new Set(),
+    rollouts: prefRollouts = [],
+  } = {}) {
+    return testFunction => {
+      return async args => {
+        let db = await getDatabase();
+        const oldData = await getStore(db, "readonly").getAll();
+        await getStore(db, "readwrite").clear();
+        await Promise.all(prefRollouts.map(r => this.add(r)));
+        const oldGraduationSet = this.GRADUATION_SET;
+        this.GRADUATION_SET = graduationSet;
+
+        try {
+          await testFunction({ ...args, prefRollouts });
+        } finally {
+          this.GRADUATION_SET = oldGraduationSet;
+          db = await getDatabase();
+          await getStore(db, "readwrite").clear();
+          const store = getStore(db, "readwrite");
+          await Promise.all(oldData.map(d => store.add(d)));
+        }
+      };
+    };
+  },
+
+  /**
+   * Add a new rollout
+   * @param {PreferenceRollout} rollout
+   */
+  async add(rollout) {
+    if (!rollout.enrollmentId) {
+      throw new Error("Rollout must have an enrollment ID");
+    }
+    const db = await getDatabase();
+    return getStore(db, "readwrite").add(rollout);
+  },
+
+  /**
+   * Update an existing rollout
+   * @param {PreferenceRollout} rollout
+   * @throws If a matching rollout does not exist.
+   */
+  async update(rollout) {
+    if (!(await this.has(rollout.slug))) {
+      throw new Error(
+        `Tried to update ${rollout.slug}, but it doesn't already exist.`
+      );
+    }
+    const db = await getDatabase();
+    return getStore(db, "readwrite").put(rollout);
+  },
+
+  /**
+   * Update many existing rollouts. More efficient than calling `update` many
+   * times in a row.
+   * @param {Array<PreferenceRollout>} rollouts
+   * @throws If any of the passed rollouts have a slug that doesn't exist in the database already.
+   */
+  async updateMany(rollouts) {
+    // Don't touch the database if there is nothing to do
+    if (!rollouts.length) {
+      return;
+    }
+
+    // Both of the below operations use .map() instead of a normal loop becaues
+    // once we get the object store, we can't let it expire by spinning the
+    // event loop. This approach queues up all the interactions with the store
+    // immediately, preventing it from expiring too soon.
+
+    const db = await getDatabase();
+    let store = await getStore(db, "readonly");
+    await Promise.all(
+      rollouts.map(async ({ slug }) => {
+        let existingRollout = await store.get(slug);
+        if (!existingRollout) {
+          throw new Error(`Tried to update ${slug}, but it doesn't exist.`);
+        }
+      })
+    );
+
+    // awaiting spun the event loop, so the store is now invalid. Get a new
+    // store. This is also a chance to get it in readwrite mode.
+    store = await getStore(db, "readwrite");
+    await Promise.all(rollouts.map(rollout => store.put(rollout)));
+  },
+
+  /**
+   * Test whether there is a rollout in storage with the given slug.
+   * @param {string} slug
+   * @returns {boolean}
+   */
+  async has(slug) {
+    const db = await getDatabase();
+    const rollout = await getStore(db, "readonly").get(slug);
+    return !!rollout;
+  },
+
+  /**
+   * Get a rollout by slug
+   * @param {string} slug
+   */
+  async get(slug) {
+    const db = await getDatabase();
+    return getStore(db, "readonly").get(slug);
+  },
+
+  /** Get all rollouts in the database. */
+  async getAll() {
+    const db = await getDatabase();
+    return getStore(db, "readonly").getAll();
+  },
+
+  /** Get all rollouts in the "active" state. */
+  async getAllActive() {
+    const rollouts = await this.getAll();
+    return rollouts.filter(rollout => rollout.state === this.STATE_ACTIVE);
+  },
+
+  /**
+   * Save in-progress preference rollouts in a sub-branch of the normandy prefs.
+   * On startup, we read these to set the rollout values.
+   */
+  async saveStartupPrefs() {
+    const prefBranch = Services.prefs.getBranch(STARTUP_PREFS_BRANCH);
+    for (const pref of prefBranch.getChildList("")) {
+      prefBranch.clearUserPref(pref);
+    }
+
+    for (const rollout of await this.getAllActive()) {
+      for (const prefSpec of rollout.preferences) {
+        lazy.PrefUtils.setPref(
+          STARTUP_PREFS_BRANCH + prefSpec.preferenceName,
+          prefSpec.value
+        );
+      }
+    }
+  },
+
+  async graduate(rollout, reason) {
+    log.debug(`Graduating rollout: ${rollout.slug}`);
+    rollout.state = this.STATE_GRADUATED;
+    const db = await getDatabase();
+    await getStore(db, "readwrite").put(rollout);
+    lazy.TelemetryEvents.sendEvent(
+      "graduate",
+      "preference_rollout",
+      rollout.slug,
+      {
+        reason,
+        enrollmentId:
+          rollout.enrollmentId || lazy.TelemetryEvents.NO_ENROLLMENT_ID_MARKER,
+      }
+    );
+  },
+};
diff --git a/toolkit/components/normandy/lib/RecipeRunner.jsm b/toolkit/components/normandy/lib/RecipeRunner.jsm
new file mode 100644
index 0000000000..fe1713c988
--- /dev/null
+++ b/toolkit/components/normandy/lib/RecipeRunner.jsm
@@ -0,0 +1,647 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+"use strict";
+
+const { XPCOMUtils } = ChromeUtils.importESModule(
+  "resource://gre/modules/XPCOMUtils.sys.mjs"
+);
+const { LogManager } = ChromeUtils.import(
+  "resource://normandy/lib/LogManager.jsm"
+);
+const { PromiseUtils } = ChromeUtils.importESModule(
+  "resource://gre/modules/PromiseUtils.sys.mjs"
+);
+
+const lazy = {};
+
+XPCOMUtils.defineLazyServiceGetter(
+  lazy,
+  "timerManager",
+  "@mozilla.org/updates/timer-manager;1",
+  "nsIUpdateTimerManager"
+);
+
+ChromeUtils.defineESModuleGetters(lazy, {
+  clearTimeout: "resource://gre/modules/Timer.sys.mjs",
+  setTimeout: "resource://gre/modules/Timer.sys.mjs",
+});
+
+XPCOMUtils.defineLazyModuleGetters(lazy, {
+  RemoteSettings: "resource://services-settings/remote-settings.js",
+  Storage: "resource://normandy/lib/Storage.jsm",
+  FilterExpressions:
+    "resource://gre/modules/components-utils/FilterExpressions.jsm",
+  TargetingContext: "resource://messaging-system/targeting/Targeting.jsm",
+  Normandy: "resource://normandy/Normandy.jsm",
+  NormandyApi: "resource://normandy/lib/NormandyApi.jsm",
+  ClientEnvironment: "resource://normandy/lib/ClientEnvironment.jsm",
+  CleanupManager: "resource://normandy/lib/CleanupManager.jsm",
+  Uptake: "resource://normandy/lib/Uptake.jsm",
+  ActionsManager: "resource://normandy/lib/ActionsManager.jsm",
+  BaseAction: "resource://normandy/actions/BaseAction.jsm",
+  RemoteSettingsClient: "resource://services-settings/RemoteSettingsClient.jsm",
+});
+
+var EXPORTED_SYMBOLS = ["RecipeRunner"];
+
+const log = LogManager.getLogger("recipe-runner");
+const TIMER_NAME = "recipe-client-addon-run";
+const REMOTE_SETTINGS_COLLECTION = "normandy-recipes-capabilities";
+const PREF_CHANGED_TOPIC = "nsPref:changed";
+
+const RUN_INTERVAL_PREF = "app.normandy.run_interval_seconds";
+const FIRST_RUN_PREF = "app.normandy.first_run";
+const SHIELD_ENABLED_PREF = "app.normandy.enabled";
+const DEV_MODE_PREF = "app.normandy.dev_mode";
+const API_URL_PREF = "app.normandy.api_url";
+const LAZY_CLASSIFY_PREF = "app.normandy.experiments.lazy_classify";
+const ONSYNC_SKEW_SEC_PREF = "app.normandy.onsync_skew_sec";
+
+// Timer last update preference.
+// see https://searchfox.org/mozilla-central/rev/11cfa0462/toolkit/components/timermanager/UpdateTimerManager.jsm#8
+const TIMER_LAST_UPDATE_PREF = `app.update.lastUpdateTime.${TIMER_NAME}`;
+
+const PREFS_TO_WATCH = [RUN_INTERVAL_PREF, SHIELD_ENABLED_PREF, API_URL_PREF];
+
+XPCOMUtils.defineLazyGetter(lazy, "gRemoteSettingsClient", () => {
+  return lazy.RemoteSettings(REMOTE_SETTINGS_COLLECTION);
+});
+
+/**
+ * cacheProxy returns an object Proxy that will memoize properties of the target.
+ */
+function cacheProxy(target) {
+  const cache = new Map();
+  return new Proxy(target, {
+    get(target, prop, receiver) {
+      if (!cache.has(prop)) {
+        cache.set(prop, target[prop]);
+      }
+      return cache.get(prop);
+    },
+    set(target, prop, value, receiver) {
+      cache.set(prop, value);
+      return true;
+    },
+    has(target, prop) {
+      return cache.has(prop) || prop in target;
+    },
+  });
+}
+
+var RecipeRunner = {
+  initializedPromise: PromiseUtils.defer(),
+
+  async init() {
+    this.running = false;
+    this.enabled = null;
+    this.loadFromRemoteSettings = false;
+    this._syncSkewTimeout = null;
+
+    this.checkPrefs(); // sets this.enabled
+    this.watchPrefs();
+    this.setUpRemoteSettings();
+
+    // Here "first run" means the first run this profile has ever done. This
+    // preference is set to true at the end of this function, and never reset to
+    // false.
+    const firstRun = Services.prefs.getBoolPref(FIRST_RUN_PREF, true);
+
+    // If we've seen a build ID from a previous run that doesn't match the
+    // current build ID, run immediately. This is probably an upgrade or
+    // downgrade, which may cause recipe eligibility to change.
+    let hasNewBuildID =
+      Services.appinfo.lastAppBuildID != null &&
+      Services.appinfo.lastAppBuildID != Services.appinfo.appBuildID;
+
+    // Dev mode is a mode used for development and QA that bypasses the normal
+    // timer function of Normandy, to make testing more convenient.
+    const devMode = Services.prefs.getBoolPref(DEV_MODE_PREF, false);
+
+    if (this.enabled && (devMode || firstRun || hasNewBuildID)) {
+      // In dev mode, if remote settings is enabled, force an immediate sync
+      // before running. This ensures that the latest data is used for testing.
+      // This is not needed for the first run case, because remote settings
+      // already handles empty collections well.
+      if (devMode) {
+        await lazy.gRemoteSettingsClient.sync();
+      }
+      let trigger;
+      if (devMode) {
+        trigger = "devMode";
+      } else if (firstRun) {
+        trigger = "firstRun";
+      } else if (hasNewBuildID) {
+        trigger = "newBuildID";
+      }
+
+      await this.run({ trigger });
+    }
+
+    // Update the firstRun pref, to indicate that Normandy has run at least once
+    // on this profile.
+    if (firstRun) {
+      Services.prefs.setBoolPref(FIRST_RUN_PREF, false);
+    }
+
+    this.initializedPromise.resolve();
+  },
+
+  enable() {
+    if (this.enabled) {
+      return;
+    }
+    this.registerTimer();
+    this.enabled = true;
+  },
+
+  disable() {
+    if (this.enabled) {
+      this.unregisterTimer();
+    }
+    // this.enabled may be null, so always set it to false
+    this.enabled = false;
+  },
+
+  /** Watch for prefs to change, and call this.observer when they do */
+  watchPrefs() {
+    for (const pref of PREFS_TO_WATCH) {
+      Services.prefs.addObserver(pref, this);
+    }
+
+    lazy.CleanupManager.addCleanupHandler(this.unwatchPrefs.bind(this));
+  },
+
+  unwatchPrefs() {
+    for (const pref of PREFS_TO_WATCH) {
+      Services.prefs.removeObserver(pref, this);
+    }
+  },
+
+  /** When prefs change, this is fired */
+  observe(subject, topic, data) {
+    switch (topic) {
+      case PREF_CHANGED_TOPIC: {
+        const prefName = data;
+
+        switch (prefName) {
+          case RUN_INTERVAL_PREF:
+            this.updateRunInterval();
+            break;
+
+          // explicit fall-through
+          case SHIELD_ENABLED_PREF:
+          case API_URL_PREF:
+            this.checkPrefs();
+            break;
+
+          default:
+            log.debug(
+              `Observer fired with unexpected pref change: ${prefName}`
+            );
+        }
+
+        break;
+      }
+    }
+  },
+
+  checkPrefs() {
+    if (!Services.prefs.getBoolPref(SHIELD_ENABLED_PREF)) {
+      log.debug(
+        `Disabling Shield because ${SHIELD_ENABLED_PREF} is set to false`
+      );
+      this.disable();
+      return;
+    }
+
+    const apiUrl = Services.prefs.getCharPref(API_URL_PREF);
+    if (!apiUrl) {
+      log.warn(`Disabling Shield because ${API_URL_PREF} is not set.`);
+      this.disable();
+      return;
+    }
+    if (!apiUrl.startsWith("https://")) {
+      log.warn(
+        `Disabling Shield because ${API_URL_PREF} is not an HTTPS url: ${apiUrl}.`
+      );
+      this.disable();
+      return;
+    }
+
+    log.debug(`Enabling Shield`);
+    this.enable();
+  },
+
+  registerTimer() {
+    this.updateRunInterval();
+    lazy.CleanupManager.addCleanupHandler(() =>
+      lazy.timerManager.unregisterTimer(TIMER_NAME)
+    );
+  },
+
+  unregisterTimer() {
+    lazy.timerManager.unregisterTimer(TIMER_NAME);
+  },
+
+  setUpRemoteSettings() {
+    if (this._alreadySetUpRemoteSettings) {
+      return;
+    }
+    this._alreadySetUpRemoteSettings = true;
+
+    if (!this._onSync) {
+      this._onSync = this.onSync.bind(this);
+    }
+    lazy.gRemoteSettingsClient.on("sync", this._onSync);
+
+    lazy.CleanupManager.addCleanupHandler(() => {
+      lazy.gRemoteSettingsClient.off("sync", this._onSync);
+      this._alreadySetUpRemoteSettings = false;
+    });
+  },
+
+  /** Called when our Remote Settings collection is updated */
+  async onSync() {
+    if (!this.enabled) {
+      return;
+    }
+
+    // Delay the Normandy run by a random amount, determined by preference.
+    // This helps alleviate server load, since we don't have a thundering
+    // herd of users trying to update all at once.
+    if (this._syncSkewTimeout) {
+      lazy.clearTimeout(this._syncSkewTimeout);
+    }
+    let minSkewSec = 1; // this is primarily is to avoid race conditions in tests
+    let maxSkewSec = Services.prefs.getIntPref(ONSYNC_SKEW_SEC_PREF, 0);
+    if (maxSkewSec >= minSkewSec) {
+      let skewMillis =
+        (minSkewSec + Math.random() * (maxSkewSec - minSkewSec)) * 1000;
+      log.debug(
+        `Delaying on-sync Normandy run for ${Math.floor(
+          skewMillis / 1000
+        )} seconds`
+      );
+      this._syncSkewTimeout = lazy.setTimeout(
+        () => this.run({ trigger: "sync" }),
+        skewMillis
+      );
+    } else {
+      log.debug(`Not skewing on-sync Normandy run`);
+      await this.run({ trigger: "sync" });
+    }
+  },
+
+  updateRunInterval() {
+    // Run once every `runInterval` wall-clock seconds. This is managed by setting a "last ran"
+    // timestamp, and running if it is more than `runInterval` seconds ago. Even with very short
+    // intervals, the timer will only fire at most once every few minutes.
+    const runInterval = Services.prefs.getIntPref(RUN_INTERVAL_PREF);
+    lazy.timerManager.registerTimer(TIMER_NAME, () => this.run(), runInterval);
+  },
+
+  async run({ trigger = "timer" } = {}) {
+    if (this.running) {
+      // Do nothing if already running.
+      return;
+    }
+    this.running = true;
+
+    await lazy.Normandy.defaultPrefsHaveBeenApplied.promise;
+
+    try {
+      this.running = true;
+      Services.obs.notifyObservers(null, "recipe-runner:start");
+
+      if (this._syncSkewTimeout) {
+        lazy.clearTimeout(this._syncSkewTimeout);
+        this._syncSkewTimeout = null;
+      }
+
+      this.clearCaches();
+      // Unless lazy classification is enabled, prep the classify cache.
+      if (!Services.prefs.getBoolPref(LAZY_CLASSIFY_PREF, false)) {
+        try {
+          await lazy.ClientEnvironment.getClientClassification();
+        } catch (err) {
+          // Try to go on without this data; the filter expressions will
+          // gracefully fail without this info if they need it.
+        }
+      }
+
+      // Fetch recipes before execution in case we fail and exit early.
+      let recipesAndSignatures;
+      try {
+        recipesAndSignatures = await lazy.gRemoteSettingsClient.get({
+          // Do not return an empty list if an error occurs.
+          emptyListFallback: false,
+        });
+      } catch (e) {
+        await lazy.Uptake.reportRunner(lazy.Uptake.RUNNER_SERVER_ERROR);
+        return;
+      }
+
+      const actionsManager = new lazy.ActionsManager();
+
+      // Execute recipes, if we have any.
+      if (recipesAndSignatures.length === 0) {
+        log.debug("No recipes to execute");
+      } else {
+        for (const { recipe, signature } of recipesAndSignatures) {
+          let suitability = await this.getRecipeSuitability(recipe, signature);
+          await actionsManager.processRecipe(recipe, suitability);
+        }
+      }
+
+      await actionsManager.finalize({
+        noRecipes: !recipesAndSignatures.length,
+      });
+
+      await lazy.Uptake.reportRunner(lazy.Uptake.RUNNER_SUCCESS);
+      Services.obs.notifyObservers(null, "recipe-runner:end");
+    } finally {
+      this.running = false;
+      if (trigger != "timer") {
+        // `run()` was executed outside the scheduled timer.
+        // Update the last time it ran to make sure it is rescheduled later.
+        const lastUpdateTime = Math.round(Date.now() / 1000);
+        Services.prefs.setIntPref(TIMER_LAST_UPDATE_PREF, lastUpdateTime);
+      }
+    }
+  },
+
+  getFilterContext(recipe) {
+    const environment = cacheProxy(lazy.ClientEnvironment);
+    environment.recipe = {
+      id: recipe.id,
+      arguments: recipe.arguments,
+    };
+    return {
+      env: environment,
+      // Backwards compatibility -- see bug 1477255.
+      normandy: environment,
+    };
+  },
+
+  /**
+   * Return the set of capabilities this runner has.
+   *
+   * This is used to pre-filter recipes that aren't compatible with this client.
+   *
+   * @returns {Set<String>} The capabilities supported by this client.
+   */
+  getCapabilities() {
+    let capabilities = new Set([
+      "capabilities-v1", // The initial version of the capabilities system.
+    ]);
+
+    // Get capabilities from ActionsManager.
+    for (const actionCapability of lazy.ActionsManager.getCapabilities()) {
+      capabilities.add(actionCapability);
+    }
+
+    // Add a capability for each transform available to JEXL.
+    for (const transform of lazy.FilterExpressions.getAvailableTransforms()) {
+      capabilities.add(`jexl.transform.${transform}`);
+    }
+
+    // Add two capabilities for each top level key available in the context: one
+    // for the `normandy.` namespace, and another for the `env.` namespace.
+    capabilities.add("jexl.context.env");
+    capabilities.add("jexl.context.normandy");
+    let env = lazy.ClientEnvironment;
+    while (env && env.name) {
+      // Walk up the class chain for ClientEnvironment, collecting applicable
+      // properties as we go. Stop when we get to an unnamed object, which is
+      // usually just a plain function is the super class of a class that doesn't
+      // extend anything. Also stop if we get to an undefined object, just in
+      // case.
+      for (const [name, descriptor] of Object.entries(
+        Object.getOwnPropertyDescriptors(env)
+      )) {
+        // All of the properties we are looking for are are static getters (so
+        // will have a truthy `get` property) and are defined on the class, so
+        // will be configurable
+        if (descriptor.configurable && descriptor.get) {
+          capabilities.add(`jexl.context.env.${name}`);
+          capabilities.add(`jexl.context.normandy.${name}`);
+        }
+      }
+      // Check for the next parent
+      env = Object.getPrototypeOf(env);
+    }
+
+    return capabilities;
+  },
+
+  /**
+   * Decide if a recipe is suitable to run, and returns a value from
+   * `BaseAction.suitability`.
+   *
+   * This checks several things in order:
+   *  - recipe signature
+   *  - capabilities
+   *  - filter expression
+   *
+   * If the provided signature does not match the provided recipe, then
+   * `SIGNATURE_ERROR` is returned. Recipes with this suitability should not be
+   * trusted. These recipes are included so that temporary signature errors on
+   * the server can be handled intelligently by actions.
+   *
+   * Capabilities are a simple set of strings in the recipe. If the Normandy
+   * client has all of the capabilities listed, then execution continues. If
+   * not, then `CAPABILITY_MISMATCH` is returned. Recipes with this suitability
+   * should be considered incompatible and treated with caution.
+   *
+   * If the capabilities check passes, then the filter expression is evaluated
+   * against the current environment. The result of the expression is cast to a
+   * boolean. If it is true, then `FILTER_MATCH` is returned. If not, then
+   * `FILTER_MISMATCH` is returned.
+   *
+   * If there is an error while evaluating the recipe's filter, `FILTER_ERROR`
+   * is returned instead.
+   *
+   * @param {object} recipe
+   * @param {object} signature
+   * @param {string} recipe.filter_expression The expression to evaluate against the environment.
+   * @param {Set<String>} runnerCapabilities The capabilities provided by this runner.
+   * @return {Promise<BaseAction.suitability>} The recipe's suitability
+   */
+  async getRecipeSuitability(recipe, signature) {
+    let generator = this.getAllSuitabilities(recipe, signature);
+    // For our purposes, only the first suitability matters, so pull the first
+    // value out of the async generator. This additionally guarantees if we fail
+    // a security or compatibility check, we won't continue to run other checks,
+    // which is good for the general case of running recipes.
+    let { value: suitability } = await generator.next();
+    switch (suitability) {
+      case lazy.BaseAction.suitability.SIGNATURE_ERROR: {
+        await lazy.Uptake.reportRecipe(
+          recipe,
+          lazy.Uptake.RECIPE_INVALID_SIGNATURE
+        );
+        break;
+      }
+
+      case lazy.BaseAction.suitability.CAPABILITIES_MISMATCH: {
+        await lazy.Uptake.reportRecipe(
+          recipe,
+          lazy.Uptake.RECIPE_INCOMPATIBLE_CAPABILITIES
+        );
+        break;
+      }
+
+      case lazy.BaseAction.suitability.FILTER_MATCH: {
+        // No telemetry needs to be sent for this right now.
+        break;
+      }
+
+      case lazy.BaseAction.suitability.FILTER_MISMATCH: {
+        // This represents a terminal state for the given recipe, so
+        // report its outcome. Others are reported when executed in
+        // ActionsManager.
+        await lazy.Uptake.reportRecipe(
+          recipe,
+          lazy.Uptake.RECIPE_DIDNT_MATCH_FILTER
+        );
+        break;
+      }
+
+      case lazy.BaseAction.suitability.FILTER_ERROR: {
+        await lazy.Uptake.reportRecipe(
+          recipe,
+          lazy.Uptake.RECIPE_FILTER_BROKEN
+        );
+        break;
+      }
+
+      case lazy.BaseAction.suitability.ARGUMENTS_INVALID: {
+        // This shouldn't ever occur, since the arguments schema is checked by
+        // BaseAction itself.
+        throw new Error(`Shouldn't get ${suitability} in RecipeRunner`);
+      }
+
+      default: {
+        throw new Error(`Unexpected recipe suitability ${suitability}`);
+      }
+    }
+
+    return suitability;
+  },
+
+  /**
+   * Some uses cases, such as Normandy Devtools, want the status of all
+   * suitabilities, not only the most important one. This checks the cases of
+   * suitabilities in order from most blocking to least blocking. The first
+   * yielded is the "primary" suitability to pass on to actions.
+   *
+   * If this function yields only [FILTER_MATCH], then the recipe fully matches
+   * and should be executed. If any other statuses are yielded, then the recipe
+   * should not be executed as normal.
+   *
+   * This is a generator so that the execution can be halted as needed. For
+   * example, after receiving a signature error, a caller can stop advancing
+   * the iterator to avoid exposing the browser to unneeded risk.
+   */
+  async *getAllSuitabilities(recipe, signature) {
+    try {
+      await lazy.NormandyApi.verifyObjectSignature(recipe, signature, "recipe");
+    } catch (e) {
+      yield lazy.BaseAction.suitability.SIGNATURE_ERROR;
+    }
+
+    const runnerCapabilities = this.getCapabilities();
+    if (Array.isArray(recipe.capabilities)) {
+      for (const recipeCapability of recipe.capabilities) {
+        if (!runnerCapabilities.has(recipeCapability)) {
+          log.debug(
+            `Recipe "${recipe.name}" requires unknown capabilities. ` +
+              `Recipe capabilities: ${JSON.stringify(recipe.capabilities)}. ` +
+              `Local runner capabilities: ${JSON.stringify(
+                Array.from(runnerCapabilities)
+              )}`
+          );
+          yield lazy.BaseAction.suitability.CAPABILITIES_MISMATCH;
+        }
+      }
+    }
+
+    const context = this.getFilterContext(recipe);
+    const targetingContext = new lazy.TargetingContext();
+    try {
+      if (await targetingContext.eval(recipe.filter_expression, context)) {
+        yield lazy.BaseAction.suitability.FILTER_MATCH;
+      } else {
+        yield lazy.BaseAction.suitability.FILTER_MISMATCH;
+      }
+    } catch (err) {
+      log.error(
+        `Error checking filter for "${recipe.name}". Filter: [${recipe.filter_expression}]. Error: "${err}"`
+      );
+      yield lazy.BaseAction.suitability.FILTER_ERROR;
+    }
+  },
+
+  /**
+   * Clear all caches of systems used by RecipeRunner, in preparation
+   * for a clean run.
+   */
+  clearCaches() {
+    lazy.ClientEnvironment.clearClassifyCache();
+    lazy.NormandyApi.clearIndexCache();
+  },
+
+  /**
+   * Clear out cached state and fetch/execute recipes from the given
+   * API url. This is used mainly by the mock-recipe-server JS that is
+   * executed in the browser console.
+   */
+  async testRun(baseApiUrl) {
+    const oldApiUrl = Services.prefs.getCharPref(API_URL_PREF);
+    Services.prefs.setCharPref(API_URL_PREF, baseApiUrl);
+
+    try {
+      lazy.Storage.clearAllStorage();
+      this.clearCaches();
+      await this.run();
+    } finally {
+      Services.prefs.setCharPref(API_URL_PREF, oldApiUrl);
+      this.clearCaches();
+    }
+  },
+
+  /**
+   * Offer a mechanism to get access to the lazily-instantiated
+   * gRemoteSettingsClient, because if someone instantiates it
+   * themselves, it won't have the options we provided in this module,
+   * and it will prevent instantiation by this module later.
+   *
+   * This is only meant to be used in testing, where it is a
+   * convenient hook to store data in the underlying remote-settings
+   * collection.
+   */
+  get _remoteSettingsClientForTesting() {
+    return lazy.gRemoteSettingsClient;
+  },
+
+  migrations: {
+    /**
+     * Delete the now-unused collection of recipes, since we are using the
+     * "normandy-recipes-capabilities" collection now.
+     */
+    async migration01RemoveOldRecipesCollection() {
+      // Don't bother to open IDB and clear on clean profiles.
+      const lastCheckPref =
+        "services.settings.main.normandy-recipes.last_check";
+      if (Services.prefs.prefHasUserValue(lastCheckPref)) {
+        // We instantiate a client, but it won't take part of sync.
+        const client = new lazy.RemoteSettingsClient("normandy-recipes");
+        await client.db.clear();
+        Services.prefs.clearUserPref(lastCheckPref);
+      }
+    },
+  },
+};
diff --git a/toolkit/components/normandy/lib/ShieldPreferences.jsm b/toolkit/components/normandy/lib/ShieldPreferences.jsm
new file mode 100644
index 0000000000..9dea64cd92
--- /dev/null
+++ b/toolkit/components/normandy/lib/ShieldPreferences.jsm
@@ -0,0 +1,84 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+"use strict";
+
+const { XPCOMUtils } = ChromeUtils.importESModule(
+  "resource://gre/modules/XPCOMUtils.sys.mjs"
+);
+
+const lazy = {};
+
+XPCOMUtils.defineLazyModuleGetters(lazy, {
+  BranchedAddonStudyAction:
+    "resource://normandy/actions/BranchedAddonStudyAction.jsm",
+  AddonStudies: "resource://normandy/lib/AddonStudies.jsm",
+  CleanupManager: "resource://normandy/lib/CleanupManager.jsm",
+  PreferenceExperiments: "resource://normandy/lib/PreferenceExperiments.jsm",
+});
+
+var EXPORTED_SYMBOLS = ["ShieldPreferences"];
+
+const NS_PREFBRANCH_PREFCHANGE_TOPIC_ID = "nsPref:changed"; // from modules/libpref/nsIPrefBranch.idl
+const PREF_OPT_OUT_STUDIES_ENABLED = "app.shield.optoutstudies.enabled";
+
+/**
+ * Handles Shield-specific preferences, including their UI.
+ */
+var ShieldPreferences = {
+  init() {
+    // Watch for changes to the Opt-out pref
+    Services.prefs.addObserver(PREF_OPT_OUT_STUDIES_ENABLED, this);
+
+    lazy.CleanupManager.addCleanupHandler(() => {
+      Services.prefs.removeObserver(PREF_OPT_OUT_STUDIES_ENABLED, this);
+    });
+  },
+
+  observe(subject, topic, data) {
+    switch (topic) {
+      case NS_PREFBRANCH_PREFCHANGE_TOPIC_ID:
+        this.observePrefChange(data);
+        break;
+    }
+  },
+
+  async observePrefChange(prefName) {
+    let prefValue;
+    switch (prefName) {
+      // If the opt-out pref changes to be false, disable all current studies.
+      case PREF_OPT_OUT_STUDIES_ENABLED: {
+        prefValue = Services.prefs.getBoolPref(PREF_OPT_OUT_STUDIES_ENABLED);
+        if (!prefValue) {
+          const action = new lazy.BranchedAddonStudyAction();
+          const studyPromises = (await lazy.AddonStudies.getAll()).map(
+            study => {
+              if (!study.active) {
+                return null;
+              }
+              return action.unenroll(study.recipeId, "general-opt-out");
+            }
+          );
+
+          const experimentPromises = (
+            await lazy.PreferenceExperiments.getAll()
+          ).map(experiment => {
+            if (experiment.expired) {
+              return null;
+            }
+            return lazy.PreferenceExperiments.stop(experiment.slug, {
+              reason: "general-opt-out",
+              caller: "observePrefChange::general-opt-out",
+            });
+          });
+
+          const allPromises = studyPromises
+            .concat(experimentPromises)
+            .map(p => p && p.catch(err => Cu.reportError(err)));
+          await Promise.all(allPromises);
+        }
+        break;
+      }
+    }
+  },
+};
diff --git a/toolkit/components/normandy/lib/Storage.jsm b/toolkit/components/normandy/lib/Storage.jsm
new file mode 100644
index 0000000000..fb8d5f475b
--- /dev/null
+++ b/toolkit/components/normandy/lib/Storage.jsm
@@ -0,0 +1,96 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+"use strict";
+
+const { XPCOMUtils } = ChromeUtils.importESModule(
+  "resource://gre/modules/XPCOMUtils.sys.mjs"
+);
+
+const lazy = {};
+
+ChromeUtils.defineESModuleGetters(lazy, {
+  JSONFile: "resource://gre/modules/JSONFile.sys.mjs",
+});
+
+var EXPORTED_SYMBOLS = ["Storage"];
+
+// Lazy-load JSON file that backs Storage instances.
+XPCOMUtils.defineLazyGetter(lazy, "lazyStore", async function() {
+  const path = PathUtils.join(
+    PathUtils.profileDir,
+    "shield-recipe-client.json"
+  );
+  const store = new lazy.JSONFile({ path });
+  await store.load();
+  return store;
+});
+
+var Storage = class {
+  constructor(prefix) {
+    this.prefix = prefix;
+  }
+
+  /**
+   * Clear ALL storage data and save to the disk.
+   */
+  static async clearAllStorage() {
+    const store = await lazy.lazyStore;
+    store.data = {};
+    store.saveSoon();
+  }
+
+  /**
+   * Sets an item in the prefixed storage.
+   * @returns {Promise}
+   * @resolves With the stored value, or null.
+   * @rejects Javascript exception.
+   */
+  async getItem(name) {
+    const store = await lazy.lazyStore;
+    const namespace = store.data[this.prefix] || {};
+    return namespace[name] || null;
+  }
+
+  /**
+   * Sets an item in the prefixed storage.
+   * @returns {Promise}
+   * @resolves When the operation is completed successfully
+   * @rejects Javascript exception.
+   */
+  async setItem(name, value) {
+    const store = await lazy.lazyStore;
+    if (!(this.prefix in store.data)) {
+      store.data[this.prefix] = {};
+    }
+    store.data[this.prefix][name] = value;
+    store.saveSoon();
+  }
+
+  /**
+   * Removes a single item from the prefixed storage.
+   * @returns {Promise}
+   * @resolves When the operation is completed successfully
+   * @rejects Javascript exception.
+   */
+  async removeItem(name) {
+    const store = await lazy.lazyStore;
+    if (this.prefix in store.data) {
+      delete store.data[this.prefix][name];
+      store.saveSoon();
+    }
+  }
+
+  /**
+   * Clears all storage for the prefix.
+   * @returns {Promise}
+   * @resolves When the operation is completed successfully
+   * @rejects Javascript exception.
+   */
+  async clear() {
+    const store = await lazy.lazyStore;
+    store.data[this.prefix] = {};
+    store.saveSoon();
+  }
+};
diff --git a/toolkit/components/normandy/lib/TelemetryEvents.jsm b/toolkit/components/normandy/lib/TelemetryEvents.jsm
new file mode 100644
index 0000000000..aa57eb504f
--- /dev/null
+++ b/toolkit/components/normandy/lib/TelemetryEvents.jsm
@@ -0,0 +1,33 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+"use strict";
+
+var EXPORTED_SYMBOLS = ["TelemetryEvents"];
+
+const TELEMETRY_CATEGORY = "normandy";
+
+const TelemetryEvents = {
+  NO_ENROLLMENT_ID_MARKER: "__NO_ENROLLMENT_ID__",
+
+  init() {
+    Services.telemetry.setEventRecordingEnabled(TELEMETRY_CATEGORY, true);
+  },
+
+  sendEvent(method, object, value, extra) {
+    for (const val of Object.values(extra)) {
+      if (val == null) {
+        throw new Error(
+          "Extra parameters in telemetry events must not be null"
+        );
+      }
+    }
+    Services.telemetry.recordEvent(
+      TELEMETRY_CATEGORY,
+      method,
+      object,
+      value,
+      extra
+    );
+  },
+};
diff --git a/toolkit/components/normandy/lib/Uptake.jsm b/toolkit/components/normandy/lib/Uptake.jsm
new file mode 100644
index 0000000000..6e38dab5ca
--- /dev/null
+++ b/toolkit/components/normandy/lib/Uptake.jsm
@@ -0,0 +1,73 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+"use strict";
+
+const { UptakeTelemetry } = ChromeUtils.import(
+  "resource://services-common/uptake-telemetry.js"
+);
+
+var EXPORTED_SYMBOLS = ["Uptake"];
+
+const COMPONENT = "normandy";
+
+var Uptake = {
+  // Action uptake
+  ACTION_NETWORK_ERROR: UptakeTelemetry.STATUS.NETWORK_ERROR,
+  ACTION_PRE_EXECUTION_ERROR: UptakeTelemetry.STATUS.CUSTOM_1_ERROR,
+  ACTION_POST_EXECUTION_ERROR: UptakeTelemetry.STATUS.CUSTOM_2_ERROR,
+  ACTION_SERVER_ERROR: UptakeTelemetry.STATUS.SERVER_ERROR,
+  ACTION_SUCCESS: UptakeTelemetry.STATUS.SUCCESS,
+
+  // Per-recipe uptake
+  RECIPE_ACTION_DISABLED: UptakeTelemetry.STATUS.CUSTOM_1_ERROR,
+  RECIPE_DIDNT_MATCH_FILTER: UptakeTelemetry.STATUS.BACKOFF,
+  RECIPE_INCOMPATIBLE_CAPABILITIES: UptakeTelemetry.STATUS.BACKOFF,
+  RECIPE_EXECUTION_ERROR: UptakeTelemetry.STATUS.APPLY_ERROR,
+  RECIPE_FILTER_BROKEN: UptakeTelemetry.STATUS.CONTENT_ERROR,
+  RECIPE_ARGUMENTS_INVALID: UptakeTelemetry.STATUS.CONTENT_ERROR,
+  RECIPE_INVALID_ACTION: UptakeTelemetry.STATUS.DOWNLOAD_ERROR,
+  RECIPE_SUCCESS: UptakeTelemetry.STATUS.SUCCESS,
+  RECIPE_INVALID_SIGNATURE: UptakeTelemetry.STATUS.SIGNATURE_ERROR,
+
+  // Uptake for the runner as a whole
+  RUNNER_NETWORK_ERROR: UptakeTelemetry.STATUS.NETWORK_ERROR,
+  RUNNER_SERVER_ERROR: UptakeTelemetry.STATUS.SERVER_ERROR,
+  RUNNER_SUCCESS: UptakeTelemetry.STATUS.SUCCESS,
+
+  async _report(status, source) {
+    // Telemetry doesn't help us much with error detection, so do some here.
+    if (!status) {
+      throw new Error(
+        `Uptake status is required (got "${JSON.stringify(status)}"`
+      );
+    }
+    if (!source) {
+      throw new Error(
+        `Uptake source is required (got "${JSON.stringify(status)}`
+      );
+    }
+    await UptakeTelemetry.report(COMPONENT, status, {
+      source: `${COMPONENT}/${source}`,
+    });
+  },
+
+  async reportRunner(status) {
+    await Uptake._report(status, "runner");
+  },
+
+  async reportRecipe(recipe, status) {
+    await Uptake._report(status, `recipe/${recipe.id}`);
+    const revisionId = parseInt(recipe.revision_id, 10);
+    Services.telemetry.keyedScalarSet(
+      "normandy.recipe_freshness",
+      recipe.id,
+      revisionId
+    );
+  },
+
+  async reportAction(actionName, status) {
+    await Uptake._report(status, `action/${actionName}`);
+  },
+};