Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/wKovacs64/hibp
An unofficial TypeScript SDK for the 'Have I been pwned?' service.
https://github.com/wKovacs64/hibp
breach breach-events breaches data-breach deno dump hack haveibeenpwned hibp javascript passwords pastes promise pwned security typescript
Last synced: 2 months ago
JSON representation
An unofficial TypeScript SDK for the 'Have I been pwned?' service.
- Host: GitHub
- URL: https://github.com/wKovacs64/hibp
- Owner: wKovacs64
- License: mit
- Created: 2016-04-08T21:33:43.000Z (almost 9 years ago)
- Default Branch: main
- Last Pushed: 2024-05-28T22:34:11.000Z (8 months ago)
- Last Synced: 2024-05-29T11:20:55.343Z (8 months ago)
- Topics: breach, breach-events, breaches, data-breach, deno, dump, hack, haveibeenpwned, hibp, javascript, passwords, pastes, promise, pwned, security, typescript
- Language: TypeScript
- Homepage: https://wkovacs64.github.io/hibp
- Size: 16.5 MB
- Stars: 110
- Watchers: 4
- Forks: 6
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG-7.x.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.txt
Awesome Lists containing this project
- awesome - hibp - A Promise-based API for querying the 'Have I been pwned?' service. (TypeScript)
README
# 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]
[![Code Coverage][coverage-image]][coverage-url]
[![All Contributors](https://img.shields.io/github/all-contributors/wKovacs64/hibp?style=flat-square)](#contributors-)## 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:[email protected]';
```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 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][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 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:
```javascript
// 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:
```javascript
// 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:
- [breach](API.md#breach)
- [breachedAccount](API.md#breachedaccount)
- [breaches](API.md#breaches)
- [dataClasses](API.md#dataclasses)
- [pasteAccount](API.md#pasteaccount)
- [pwnedPassword](API.md#pwnedpassword)
- [pwnedPasswordRange](API.md#pwnedpasswordrange)
- [search](API.md#search)
- [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);
}
}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 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][webpack] or, more likely, whatever your framework of choice uses under the
hood.1. 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 `` tag) is to use the
[unpkg][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][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):```html
<script src="https://unpkg.com/[email protected]">
```1. ESM for Browsers
Modern browsers now [support][caniuse-esm] importing ECMAScript modules via
`` tags. Like the UMD option above, this build is also available the
[unpkg][unpkg] CDN (and the same versioning rules apply), but you must specify the full path
(including the file extension). For example:```html
<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();
```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 RunKit.][runkit]
## 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
BanManagerSend 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
[coverage-image]: https://img.shields.io/codecov/c/github/wKovacs64/hibp/main.svg?style=flat-square
[coverage-url]: https://codecov.io/gh/wKovacs64/hibp/branch/main
[deno]: https://deno.land/
[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
[webpack]: https://webpack.js.org
[runkit]: https://runkit.com/npm/hibp
[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)):
Justin Hall
💻 📖 🚇 🚧 👀 ⚠️
Troy Hunt
🔣
Jelle Kralt
💻
Anton W
🐛
Daniel Adams
💻
Markus Dolic
🐛
Jonathan Sharpe
💻
Ryan
🐛
Stuart McGregor
🐛
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors)
specification. Contributions of any kind welcome!