hibp
    TypeScript icon, indicating that this package has built-in type declarations

    11.0.0 • Public • Published
    logo

    hibp

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

    npm Version Build Status Code Coverage semantic-release All Contributors

    Installation

    In Node.js:

    npm install hibp

    In Deno (via Skypack):

    // Replace x.y.z with the desired hibp version      ↓ ↓ ↓
    import * as hibp from 'https://cdn.skypack.dev/hibp@x.y.z?dts';

    See the browser section below for information on how to use it in the browser.

    Features (🔑 = requires an API key)

    • 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)
    • Written in TypeScript, so all modules come fully typed

    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', { apiKey: 'my-api-key' })
      .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 efficient 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 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>
    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 file extension). For example:

      <script type="module">
        // Replace x.y.z with the desired hibp version      ↓ ↓ ↓
        import { dataClasses } from 'https://unpkg.com/hibp@x.y.z/dist/browser/hibp.module.js';
      
        const logDataClasses = async () => {
          console.table(await dataClasses());
        };
      
        logDataClasses();
      </script>

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

    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.

    Contributors

    Thanks goes to these wonderful people (emoji key):


    Justin Hall

    💻 📖 🚇 🚧 👀 ⚠️

    Troy Hunt

    🔣

    Jelle Kralt

    💻

    Anton W

    🐛

    Daniel Adams

    💻

    Markus Dolic

    🐛

    Jonathan Sharpe

    💻

    This project follows the all-contributors specification. Contributions of any kind welcome!

    Install

    npm i hibp

    DownloadsWeekly Downloads

    4,237

    Version

    11.0.0

    License

    MIT

    Unpacked Size

    329 kB

    Total Files

    76

    Last publish

    Collaborators

    • wkovacs64