[DEPRECATED]

Warning: this project is no longer maintained. Please see pwned for a CLI or hibp for Web and Node.js.

---

hibp microservice on StdLib

Functions for querying the 'Have I been pwned?' API.

• breach
• breachedAccount
• breaches
• dataClasses
• pasteAccount
• pwnedPassword
• search

breach

Description

Fetches breach data for a single breach.

Parameters

• breachName: the name of a breach in the system

Data Returned

See the breach model section of the API documentation for a description of the data returned.

Usage

Command-line:

$ lib wKovacs64.hibp.breach --breachName Adobe

Shorthand for the same request:

$ lib wKovacs64.hibp.breach Adobe

HTTP:

https://wkovacs64.lib.id/hibp/breach/?breachName=Adobe

Web and Node.js:

const lib = require('lib');
const { breach } = lib.wKovacs64.hibp;

breach({ breachName: 'Adobe' })
  .then(data => {
    // handle data
  })
  .catch(err => {
    // handle error
  });

breachedAccount

Description

Fetches all breach data for an account.

Parameters

• account: a username or email address (required)
• domain: a domain by which to filter the results (optional, default: all domains)
• truncate: truncate the results to only include the name of each breach (optional, default: false)

Data Returned

See the breach model section of the API documentation for a description of the data returned.

Usage

Command-line:

Return a JSON object with breach information for the specified account:

$ lib wKovacs64.hibp.breachedAccount --account foo

Truncate the same results to just the breach names:

$ lib wKovacs64.hibp.breachedAccount --account foo --truncate true

HTTP:

https://wkovacs64.lib.id/hibp/breachedAccount/?account=foo

Limit to a specific domain:

https://wkovacs64.lib.id/hibp/breachedAccount/?account=foo&domain=adobe.com

Web and Node.js:

const lib = require('lib');
const { breachedAccount } = lib.wKovacs64.hibp;

breachedAccount({ account: 'foo' })
  .then(data => {
    // handle data
  })
  .catch(err => {
    // handle error
  });

breaches

Description

Fetches all breach data in the system.

Parameters

• domain: a domain by which to filter the results (optional, default: all domains)

Data Returned

See the breach model section of the API documentation for a description of the data returned.

Usage

Command-line:

$ lib wKovacs64.hibp.breaches

Filter by domain:

$ lib wKovacs64.hibp.breaches --domain adobe.com

HTTP:

https://wkovacs64.lib.id/hibp/breaches/

Web and Node.js:

const lib = require('lib');
const { breaches } = lib.wKovacs64.hibp;

breaches()
  .then(data => {
    // handle data
  })
  .catch(err => {
    // handle error
  });

dataClasses

Description

Fetches all data classes in the system.

Parameters

• none

Data Returned

See the data classes section of the API documentation for a description of the data returned.

Usage

Command-line:

$ lib wKovacs64.hibp.dataClasses

HTTP:

https://wkovacs64.lib.id/hibp/dataClasses/

Web and Node.js:

const lib = require('lib');
const { dataClasses } = lib.wKovacs64.hibp;

dataClasses()
  .then(data => {
    // handle data
  })
  .catch(err => {
    // handle error
  });

pasteAccount

Description

Fetches all pastes for an email address.

Parameters

• email: the email address to query (required)

Data Returned

See the paste model section of the API documentation for a description of the data returned.

Usage

Command-line:

$ lib wKovacs64.hibp.pasteAccount --email foo@bar.com

Shorthand for the same request:

$ lib wKovacs64.hibp.pasteAccount foo@bar.com

HTTP:

https://wkovacs64.lib.id/hibp/pasteAccount/?email=foo@bar.com

Web and Node.js:

const lib = require('lib');
const { pasteAccount } = lib.wKovacs64.hibp;

pasteAccount({ email: 'foo@bar.com' })
  .then(data => {
    // handle data
  })
  .catch(err => {
    // handle error
  });

pwnedPassword

Description

Securely fetches the number of times the given password has been exposed in a breach. See the Pwned Passwords section of the API documentation for more information.

Parameters

• password: a password as a plain text string (required)

Data Returned

pwnedPassword returns a number.

Usage

Command-line:

Return a number corresponding to the number of times the password has been exposed in a breach:

$ lib wKovacs64.hibp.pwnedPassword --password Password1234

HTTP:

https://wkovacs64.lib.id/hibp/pwnedPassword/?password=Password1234

Web and Node.js:

const lib = require('lib');
const { pwnedPassword } = lib.wKovacs64.hibp;

pwnedPassword({ password: 'Password1234' })
  .then(pwnCount => {
    // handle result
  })
  .catch(err => {
    // handle error
  });

search

Description

Fetches all breaches and all pastes associated with a given account.

Parameters

• account: a username or email address (required)
• domain: a domain by which to filter breach results (optional, default: all domains)
• truncate: truncate the results to only include the name of each breach (optional, default: false)

Data Returned

search returns a JSON object with a breaches key and a pastes key. See the breach model and paste model sections of the API documentation (respectively) for descriptions of the values of those keys. Each value may independently be null if no corresponding data was found.

Usage

Command-line:

Return a JSON object with breach and paste information for the specified account:

$ lib wKovacs64.hibp.search --account foo

Return a JSON object with breach and paste information for the specified email address:

$ lib wKovacs64.hibp.search --account foo@bar.com

HTTP:

https://wkovacs64.lib.id/hibp/search/?account=foo

Limit breach data to a specific domain:

https://wkovacs64.lib.id/hibp/search/?account=foo&domain=adobe.com

Web and Node.js:

const lib = require('lib');
const { search } = lib.wKovacs64.hibp;

search({ account: 'foo' })
  .then(data => {
    // handle data
  })
  .catch(err => {
    // handle error
  });

✍ Author's Note

There's a good chance this project adds no value. I primarily did it as an introduction to microservices on StdLib. The current access methods probably have superior, preexisting alternatives:

• Command-line: pwned is more flexible.
• HTTP: Just query the API endpoints directly?
• Web and Node.js: hibp powers this microservice. Use that.