Skip to content
Switch branches/tags


Failed to load latest commit information.
Latest commit message
Commit time

Firefox Monitor Server


Firefox Monitor notifies users when their credentials have been compromised in a data breach.

This code is for the service & website.

Breach data is powered by

See the Have I Been Pwned about page for the "what" and "why" of data breach alerts.


Please refer to our coding standards information for code styles, naming conventions and other methodologies.



  1. Clone and change to the directory:

    git clone
    cd blurts-server
  2. Install dependencies:

    npm install
  3. Copy the .env-dist file to .env:

    cp .env-dist .env


  1. Run the server:

    npm start

Note: npm start uses onchange and nodemon to automatically detect file changes, re-compile static assets, and restart the express process. If you want more control, see the scripts section of package.json for more commands.

  1. Navigate to localhost:6060/


To create the database tables ...

  1. Create the blurts database:

    createdb blurts
    createdb test-blurts # for tests
  2. Update the DATABASE_URL value in your .env file with your local db credentials:

  3. Run the migrations:

    npm run db:migrate


The included .env-dist sets DEBUG_DUMMY_SMTP=1 which disables emails.

To send emails, you'll need to unset DEBUG_DUMMY_SMTP and supply real SMTP config values for sending email.

You can set and source these via the .env file, or set them directly:

export SMTP_HOST=<your-smtp-host>
export SMTP_PORT=<your-smtp-port>
export SMTP_USERNAME=<your-username>
export SMTP_PASSWORD=<your-password>
Trigger a breach alert email

To trigger a breach alert email, you need to make a POST /hibp/notify request:

  • Authorization: Bearer header token value that matches HIBP_NOTIFY_TOKEN
  • Content-Type: application/json header
  • JSON body with breachName, hashPrefix, and hashSuffix values
    • breachName - string of a breach name in Monitor
    • hashPrefix - string of first 6 chars of a subscriber's primary_sha1
    • hashSuffix - array of strings of the remaining chars of the sha1 hash

E.g., a localhost curl command that triggers a breach alert email for the Adobe breach to the subscriber:

curl -v -H "Authorization: Bearer unsafe-default-token-for-dev" -H "Content-Type: application/json" -d '{"breachName": "Adobe", "hashPrefix": "365050", "hashSuffixes": ["53cbb89874fc738c0512daf12bc4d91765"]}' http://localhost:6060/hibp/notify

Firefox Accounts

Subscribe with a Firefox Account is controlled via the FXA_ENABLED environment variable. (See .env-dist)

The repo comes with a development FxA oauth app pre-configured in .env, which should work fine running the app on http://localhost:6060. You'll need to get the OAUTH_CLIENT_SECRET value from someone in #fxmonitor-engineering.


The full test suite can be run via npm test.

Individual tests

To run individual tests, use NODE_ENV=tests and jest:

NODE_ENV=tests jest --runInBand tests/home.test.js

To run tests with interactive debugger lines enabled:

NODE_ENV=tests node inspect --harmony ./node_modules/.bin/jest tests/home.test.js

Test Firefox Integration

Firefox's internal about:protections page ("Protections Dashboard") fetches and displays breach stats for Firefox users who are signed into their FXA.

To test this part of Monitor:

  1. Set a Firefox profile to use the staging Firefox Accounts server.
  2. In the same profile, go to about:config and replace all values with http://localhost:6060
  3. Restart Firefox with that profile.
  4. Go to about:protections
  5. Everything should be using your localhost instance of Monitor.


After installing the dependencies, you can lint the code by calling:

npm run lint


Firefox Monitor Breach Alerts is designed with 12-factor methodology.

Deploy on Heroku

You will need to set some required environment variables on Heroku.

heroku config:set COOKIE_SECRET=unsafe-cookie-secret-for-heroku
heroku config:set DEBUG_DUMMY_SMTP=1

And any others, depending on the features you're running on Heroku - e.g., Email or Firefox Accounts.


Firefox Monitor arms you with tools to keep your personal information safe. Find out what hackers already know about you and learn how to stay a step ahead of them.





No packages published