hibp
An unofficial TypeScript SDK for Troy Hunt's Have I been pwned? service.
Installation
In Node.js:
npm install hibp
In Deno:
import * as hibp from 'npm:hibp@x.y.z';
See the browser section below for information on how to use it in the
browser.
- 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 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 your subscription status 🔑
- 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 { dataClasses, search } from 'hibp';
import * as hibp from 'hibp';
CommonJS module syntax:
const { dataClasses, search } = require('hibp');
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';
async function main() {
try {
const data = await search('someAccountOrEmail', { apiKey: 'my-api-key' });
if (data.breaches || data.pastes) {
console.log(data);
} else {
console.log('Good news — no pwnage found!');
}
} catch (err) {
console.log(err.message);
}
}
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 several options for using this library in a browser environment:
-
Bundled
The most efficient and recommended method is to bundle it with client-side code using a module
bundler like webpack or, more likely, whatever your framework of choice uses under the
hood.
-
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>
-
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">
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):
This project follows the all-contributors
specification. Contributions of any kind welcome!