A Promise-based API for querying the 'Have I been pwned?' service.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
cypress
example Add ignores for eslint and prettier and reformat Nov 6, 2017
src
test
.babelrc.js
.editorconfig
.eslintignore
.eslintrc.js
.gitattributes
.gitignore
.prettierignore
.prettierrc
.size-snapshot.json
.travis.yml Add an ESM for browsers build (#49) Oct 17, 2018
API.md
CHANGELOG.md
CONTRIBUTING.md Update contribution guide Nov 24, 2017
LICENSE.txt
MIGRATION.md
README.md
RELEASING.md
cypress.json
husky.config.js
jest.config.js
lint-staged.config.js
package.json
renovate.json
rollup.config.js Stop enforcing identical size snapshots Oct 23, 2018
serve.json Add an ESM for browsers build (#49) Oct 17, 2018
yarn.lock Update rollup-plugin-node-resolve to v4 (#51) Dec 9, 2018

README.md

logo

hibp

A Promise-based API for querying Troy Hunt's Have I been pwned? service.

npm Version Build Status Code Coverage

Installation

Locally via yarn:

yarn add hibp

Or, npm:

npm install --save hibp

Browser via CDN (see below for more information):

<script src="https://unpkg.com/hibp@7.2.2"></script>

Features

  • Get a single breach event
  • Get all breaches for an account
  • Get all breach events in the system
  • Get all data classes
  • Get all pastes for an account
  • Securely check a password to see if it has been exposed in a data breach
  • Check a SHA-1 prefix to see if it has been exposed in a data breach
  • Search for an account in both breaches and pastes at the same time
  • All queries return a Promise
  • Available server-side (Node.js) and client-side (browser)

Usage

ECMAScript module syntax:
// import individual modules as needed
import { dataClasses, search } from 'hibp';
// or, import all modules into a local namespace
import * as hibp from 'hibp';
CommonJS module syntax:
// require individual modules as needed
const { dataClasses, search } = require('hibp');
// or, require all modules into a local namespace
const hibp = require('hibp');

The following modules are available:

Please see the API reference for more detailed usage information and examples.

Quick-Start Example

import { search } from 'hibp';

search('someAccountOrEmail')
  .then(data => {
    if (data.breaches || data.pastes) {
      // Bummer...
      console.log(data);
    } else {
      // Phew! We're clear.
      console.log('Good news — no pwnage found!');
    }
  })
  .catch(err => {
    // Something went wrong.
    console.log(err.message);
  });

Using in the browser

Prerequisite: This module requires a Promise implementation to exist in the global namespace prior to being loaded. Therefore, to facilitate usage in browsers without native Promise support, you are responsible for providing a polyfill. I recommend es6-promise.

You have several options for using this library in a browser environment:

  1. Bundled

    The most performant and recommended method is to bundle it with client-side code using a module bundler like webpack. If your build process honors the module field in package.json, you can import the ECMAScript module as described above. Otherwise, the main field resolves to the CommonJS module version.

  2. UMD

    There is also a Universal Module Definition (UMD) build provided in the package dist directory for usage in the browser. When using this build, an hibp object will be added to the browser's window object.

    The recommended way to include the UMD build (when using a <script> tag) is to use the unpkg CDN, specifying the exact version you want. If you don't specify a version, the latest tag will be used, which could be dangerous if/when there are breaking changes made to the API. See unpkg for details and advanced version specification, but generally you will want to do the following (replacing x.y.z with the version you want):

    <script src="https://unpkg.com/hibp@x.y.z"></script>

    Development and production (minified) UMD builds are also provided for manual download if desired:

  3. ESM for Browsers

    Modern browsers now support importing ECMAScript modules via <script type="module"> tags. Like the UMD option above, this build is also available the unpkg CDN (and the same versioning rules apply), but you must specify the full path including the .mjs file extension. For example:

    <script type="module">
      import { dataClasses } from 'https://unpkg.com/hibp/dist/hibp.min.mjs@x.y.z';
    
      const logDataClasses = async () => {
        console.table(await dataClasses());
      };
    
      logDataClasses();
    </script>

    Development and production (minified) ESM builds are also provided for manual download if desired:

    For more information on ESM in the browser, check out Using JavaScript modules on the web.

Try It Out

Test hibp in your browser with RunKit.

Projects Using hibp

Send me a PR or an email and I'll add yours to the list.

License

This module is distributed under the MIT License.