hibp

An unofficial TypeScript SDK for Troy Hunt's Have I been pwned? service.

Installation

In Node.js:

npm install hibp

In Deno:

// Replace x.y.z with the desired hibp version
import * as hibp from "npm:[email protected]";

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

Features

• All queries return a Promise
• Provide your own AbortSignal to cancel in-flight requests
• Available server-side (e.g., Node.js) and client-side (browser)
• Written in TypeScript, so all modules come fully typed

API features are grouped by the HIBP plans whose API key unlocks them.

No API key

• Get the most recently added breach
• Get a single breach event
• Get all breach events in the system
• Get all data classes
• Get data class names and descriptions
• Securely check a password to see if it has been exposed in a data breach
• Check a SHA-1 or NTLM prefix to see if it has been exposed in a data breach

/ /

• Get all breaches for an account
• Get all pastes for an account
• Search for an account in both breaches and pastes at the same time
• Get your subscription status, domain limits, and plan capabilities

/

• Get all breached email addresses for a domain
• Get all subscribed domains

/

• Search breaches by a six-character SHA-1 email prefix

• Get all stealer log domains for an email address
• Get all stealer log email aliases for an email domain
• Get all stealer log email addresses for a website domain
• Generate and verify DNS domain verification tokens
• Request domain verification approval emails

Usage

// import individual modules as needed
import { dataClasses, search } from "hibp";

// or, import all modules into a local namespace
import * as hibp from "hibp";

The following modules are available:

• breach
• breachedAccount
• breachedAccountRange
• breachedDomain
• breaches
• dataClasses
• dataClassDescriptions
• generateDnsToken
• latestBreach
• pasteAccount
• pwnedPassword
• pwnedPasswordRange
• search
• sendEmail
• stealerLogsByEmail
• stealerLogsByEmailDomain
• stealerLogsByWebsiteDomain
• subscribedDomains
• subscriptionStatus
• verifyDnsToken

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

Quick-Start Example

import { search } from "hibp";

async function main() {
  try {
    const data = await search("someAccountOrEmail", { apiKey: "my-api-key" });
    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);
  }
}

void main();

Rate Limiting

The haveibeenpwned.com API rate limits requests to prevent abuse. In the event you get rate limited, the module will throw a custom RateLimitError which will include a retryAfterSeconds property so you know when you can try the call again (as a number, unless the remote API did not provide one, in which case it will be undefined - but that should never happen).

Using in the browser

You have a couple of 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, most likely dictated by your web application framework of choice.

2. ESM for Browsers

   Alternatively, you can also import the library directly in your HTML via <script type="module"> tags in modern browsers. The pre-bundled module is available through the unpkg CDN, but you must specify the full path (including the file extension). It's also strongly recommended to include the exact version number as well, otherwise 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 you will probably want to do the following (replacing x.y.z with the version you want):

   <script type="module">
     // Replace x.y.z with the desired hibp version      ↓ ↓ ↓
     import { dataClasses } from "https://unpkg.com/[email protected]/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 StackBlitz.

This is the beginning of the README. Read the rest at the original. Read the full README ↗