hibp

KO | EN

gitlite — search

#hacktoberfest #golang #android #machine-learning #deep-learning #linux #macos #cli #kubernetes #awesome-list #vue #pytorch #ios #openai

(★ 117)

An unofficial TypeScript SDK for the 'Have I been pwned?' service.

hibp Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# hibp

_An unofficial TypeScript SDK for [Troy Hunt][troy]'s [Have I been pwned?][haveibeenpwned] service._

[![npm Version][npm-image]][npm-url] [![Build Status][ci-image]][ci-url]
[![All Contributors](https://img.shields.io/github/all-contributors/wKovacs64/hibp?style=flat-square)](https://raw.githubusercontent.com/wKovacs64/hibp/main/)

## Installation

In Node.js:

```shell
npm install hibp
```

In [Deno][deno]:

```ts
// Replace x.y.z with the desired hibp version
import * as hibp from "npm:hibp@x.y.z";
```

See the [browser](#using-in-the-browser) section below for information on how to use it in the
browser.

## Features (🔑 = [requires][api-key-blog-post] an [API key][get-api-key])

- Get the most recently added breach
- Get a single breach event
- Get all breaches for an account 🔑
- Get all breached email addresses for a domain 🔑
- Get all breach events in the system
- Get all data classes
- Get all pastes for an account 🔑
- [Securely][search-by-range] 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
- Search for an account in both breaches and pastes at the same time 🔑
- 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 🔑
- Get all subscribed domains 🔑
- Get your subscription status 🔑
- 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

## Usage

```typescript
// 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](API.md#breach)
- [breachedAccount](API.md#breachedaccount)
- [breachedDomain](API.md#breacheddomain)
- [breaches](API.md#breaches)
- [dataClasses](API.md#dataclasses)
- [latestBreach](API.md#latestbreach)
- [pasteAccount](API.md#pasteaccount)
- [pwnedPassword](API.md#pwnedpassword)
- [pwnedPasswordRange](API.md#pwnedpasswordrange)
- [search](API.md#search)
- [stealerLogsByEmail](API.md#stealerlogsbyemail)
- [stealerLogsByEmailDomain](API.md#stealerlogsbyemaildomain)
- [stealerLogsByWebsiteDomain](API.md#stealerlogsbywebsitedomain)
- [subscribedDomains](API.md#subscribeddomains)
- [subscriptionStatus](API.md#subscriptionstatus)

Please see the [API reference](API.md) for more detailed usage information and examples.

#### Quick-Start Example

```javascript
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][haveibeenpwned-rate-limiting] 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.

1. ESM for Browsers

Alternatively, you can also import the library directly in your HTML via `<script type="module">`
 tags in [modern browsers][caniuse-esm]. The pre-bundled module is available through the
 [unpkg][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][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):

```html
 <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][js-modules].

## Try It Out

[Test hibp in your browser with StackBlitz.][stackblitz]

## Projects Using hibp

- [pwned][pwned] - a command-line tool for querying the '[Have I been pwned?][haveibeenpwned]'
  service
- [Password Lense][pwl] - a static web application to reveal character types in a password
- [Plasmic](https://www.plasmic.app/) - the open-source visual builder for your tech stack
- [Medplum](https://www.medplum.com/) - fast and easy healthcare dev
- [Hasura Backend Plus](https://nhost.github.io/hasura-backend-plus/) - Authentication & Storage for
  Hasura
- [Staart API](https://staart.js.org/api/) - a Node.js backend starter for SaaS startups
- [BanManager-WebUI](https://github.com/BanManagement/BanManager-WebUI) - Web interface for
  BanManager

Send me a [PR][pulls] or an email and I'll add yours to the list!

## License

This module is distributed under the [MIT License][license].

[npm-image]: https://img.shields.io/npm/v/hibp.svg?style=flat-square
[npm-url]: https://www.npmjs.com/package/hibp
[ci-image]: https://img.shields.io/github/actions/workflow/status/wKovacs64/hibp/ci.yml?logo=github&style=flat-square
[ci-url]: https://github.com/wKovacs64/hibp/actions?query=workflow%3Aci
[deno]: https://deno.com/
[troy]: https://www.troyhunt.com
[haveibeenpwned]: https://haveibeenpwned.com
[haveibeenpwned-rate-limiting]: https://haveibeenpwned.com/API/v3#RateLimiting
[search-by-range]: https://haveibeenpwned.com/API/v2#SearchingPwnedPasswordsByRange
[api-key-blog-post]: https://www.troyhunt.com/authentication-and-the-have-i-been-pwned-api/
[get-api-key]: https://haveibeenpwned.com/API/Key
[unpkg]: https://unpkg.com
[caniuse-esm]: https://caniuse.com/#feat=es6-module
[js-modules]: https://v8.dev/features/modules#browser
[stackblitz]: https://stackblitz.com/edit/stackblitz-starters-atyrc52c?file=index.js
[pwned]: https://github.com/wKovacs64/pwned
[pulls]: https://github.com/wKovacs64/hibp/pulls
[pwl]: https://pwl.netlify.com/
[license]: https://github.com/wKovacs64/hibp/tree/main/LICENSE.txt

## Contributors ✨

Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

<table>
 <tbody>
 <tr>
 <td align="center" valign="top" width="14.28%"><a href="https://github.com/wKovacs64"><img src="https://avatars.githubusercontent.com/u/1288694?v=4?s=100" width="100px;" alt="Justin Hall"/> Justin Hall</a> <a href="https://github.com/wKovacs64/hibp/commits?author=wKovacs64" title="Code">💻</a> <a href="https://github.com/wKovacs64/hibp/commits?author=wKovacs64" title="Documentation">📖</a> <a href="#infra-wKovacs64" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="#maintenance-wKovacs64" title="Maintenance">🚧</a> <a href="https://github.com/wKovacs64/hibp/pulls?q=is%3Apr+reviewed-by%3AwKovacs64" title="Reviewed Pull Requests">👀</a> <a href="https://github.com/wKovacs64/hibp/commits?author=wKovacs64" title="Tests">⚠️</a></td>
 <td align="center" valign="top" width="14.28%"><a href="https://www.troyhunt.com"><img src="https://avatars.githubusercontent.com/u/273244?v=4?s=100" width="100px;" alt="Troy Hunt"/> Troy Hunt</a> <a href="#data-troyhunt" title="Data">🔣</a></td>
 <td align="center" valign="top" width="14.28%"><a href="https://jellekralt.com"><img src="https://avatars.githubusercontent.com/u/214558?v=4?s=100" width="100px;" alt="Jelle Kralt"/> Jelle Kralt</a> <a href="https://github.com/wKovacs64/hibp/commits?author=jellekralt" title="Code">💻</a></td>
 <td align="center" valign="top" width="14.28%"><a href="https://github.com/timaschew"><img src="https://avatars.githubusercontent.com/u/110870?v=4?s=100" width="100px;" alt="Anton W"/> Anton W</a> <a href="https://github.com/wKovacs64/hibp/issues?q=author%3Atimaschew" title="Bug reports">🐛</a></td>
 <td align="center" valign="top" width="14.28%"><a href="https://github.com/danieladams456"><img src="https://avatars.githubusercontent.com/u/3953840?v=4?s=100" width="100px;" alt="Daniel Adams"/> Daniel Adams</a> <a href="https://github.com/wKovacs64/hibp/commits?author=danieladams456" title="Code">💻</a></td>
 <td align="center" valign="top" width="14.28%"><a href="https://twitter.com/d0gb3r7"><img src="https://avatars.githubusercontent.com/u/454308?v=4?s=100" width="100px;" alt="Markus Dolic"/> Markus Dolic</a> <a href="https://github.com/wKovacs64/hibp/issues?q=author%3Ayelworc" title="Bug reports">🐛</a></td>
 <td align="center" valign="top" width="14.28%"><a href="https://github.com/textbook/about"><img src="https://avatars.githubusercontent.com/u/785939?v=4?s=100" width="100px;" alt="Jonathan Sharpe"/> Jonathan Sharpe</a> <a href="https://github.com/wKovacs64/hibp/commits?author=textbook" title="Code">💻</a></td>
 </tr>
 <tr>
 <td align="center" valign="top" width="14.28%"><a href="https://github.com/ArcadeRenegade"><img src="https://avatars.githubusercontent.com/u/13874898?v=4?s=100" width="100px;" alt="Ryan"/> Ryan</a> <a href="https://github.com/wKovacs64/hibp/issues?q=author%3AArcadeRenegade" title="Bug reports">🐛</a></td>
 <td align="center" valign="top" width="14.28%"><a href="https://github.com/PodStuart"><img src="https://avatars.githubusercontent.com/u/107403965?v=4?s=100" width="100px;" alt="Stuart McGregor"/> Stuart McGregor</a> <a href="https://github.com/wKovacs64/hibp/issues?q=author%3APodStuart" title="Bug reports">🐛</a></td>
 </tr>
 </tbody>
</table>

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors)
specification. Contributions of any kind welcome!

hibp

hibp Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

hibp

hibp Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README