Skip to content

Latest commit

 

History

History
594 lines (531 loc) · 23.5 KB

API.md

File metadata and controls

594 lines (531 loc) · 23.5 KB
Raw

Functions

breach(breachName, [options]) ⇒ Promise.<Breach> | Promise.<null>

Fetches data for a specific breach event.

breachedAccount(account, [options]) ⇒ Promise.<Array.<Breach>> | Promise.<null>

Fetches breach data for a specific account.

🔑 haveibeenpwned.com requires an API key from https://haveibeenpwned.com/API/Key for the breachedaccount endpoint. The apiKey option here is not explicitly required, but direct requests made without it will fail (unless you specify a baseUrl to a proxy that inserts a valid API key on your behalf).

breaches([options]) ⇒ Promise.<Array.<Breach>>

Fetches all breach events in the system.

dataClasses([options]) ⇒ Promise.<Array.<string>> | Promise.<null>

Fetches all data classes in the system.

pasteAccount(email, [options]) ⇒ Promise.<Array.<Paste>> | Promise.<null>

Fetches paste data for a specific account (email address).

🔑 haveibeenpwned.com requires an API key from https://haveibeenpwned.com/API/Key for the pasteaccount endpoint. The apiKey option here is not explicitly required, but direct requests made without it will fail (unless you specify a baseUrl to a proxy that inserts a valid API key on your behalf).

pwnedPasswordRange(prefix, [options]) ⇒ Promise.<PwnedPasswordSuffixes>

Fetches the SHA-1 or NTLM hash suffixes for the given 5-character hash prefix.

When a password hash with the same first 5 characters is found in the Pwned Passwords repository, the API will respond with an HTTP 200 and include the suffix of every hash beginning with the specified prefix, followed by a count of how many times it appears in the data set. This function parses the response and returns a more structured format.

pwnedPassword(password, [options]) ⇒ Promise.<number>

Fetches the number of times the the given password has been exposed in a breach (0 indicating no exposure). The password is given in plain text, but only the first 5 characters of its SHA-1 hash will be submitted to the API.

search(account, [options]) ⇒ Promise.<SearchResults>

Fetches all breaches and all pastes associated with the provided account (email address or username). Note that the remote API does not support querying pastes by username (only email addresses), so in the event the provided account is not a valid email address, only breach data is queried and the "pastes" field of the resulting object will always be null. This is exactly how searching via the current web interface behaves, which this convenience method is designed to mimic.

🔑 haveibeenpwned.com requires an API key from https://haveibeenpwned.com/API/Key for the breachedaccount and pasteaccount endpoints. The apiKey option here is not explicitly required, but direct requests made without it will fail (unless you specify a baseUrl to a proxy that inserts a valid API key on your behalf).

subscriptionStatus([options]) ⇒ Promise.<SubscriptionStatus>

Fetches the current status of your HIBP subscription (API key).

🔑 haveibeenpwned.com requires an API key from https://haveibeenpwned.com/API/Key for the subscription/status endpoint. The apiKey option here is not explicitly required, but direct requests made without it will fail (unless you specify a baseUrl to a proxy that inserts a valid API key on your behalf).

Typedefs

Breach : object

An object representing a breach.

Paste : object

An object representing a paste.

PwnedPasswordSuffixes : Object.<string, number>

An object mapping an exposed password hash suffix (corresponding to a given hash prefix) to how many times it occurred in the Pwned Passwords repository.

SearchResults : object

An object representing search results.

SubscriptionStatus : object

An object representing the status of your HIBP subscription.

breach(breachName, [options]) ⇒ Promise.<Breach> | Promise.<null>

Fetches data for a specific breach event.

Kind: global function
Returns: Promise.<Breach> | Promise.<null> - a Promise which resolves to an object representing a breach (or null if no breach was found), or rejects with an Error

Param Type Description
breachName string the name of a breach in the system
[options] object a configuration object
[options.baseUrl] string a custom base URL for the haveibeenpwned.com API endpoints (default: https://haveibeenpwned.com/api/v3)
[options.timeoutMs] number timeout for the request in milliseconds (default: none)
[options.userAgent] string a custom string to send as the User-Agent field in the request headers (default: hibp <version>)

Example

try {
  const data = await breach("Adobe");
  if (data) {
    // ...
  } else {
    // ...
  }
} catch (err) {
  // ...
}

breachedAccount(account, [options]) ⇒ Promise.<Array.<Breach>> | Promise.<null>

Fetches breach data for a specific account.

🔑 haveibeenpwned.com requires an API key from https://haveibeenpwned.com/API/Key for the breachedaccount endpoint. The apiKey option here is not explicitly required, but direct requests made without it will fail (unless you specify a baseUrl to a proxy that inserts a valid API key on your behalf).

Kind: global function
Returns: Promise.<Array.<Breach>> | Promise.<null> - a Promise which resolves to an array of breach objects (or null if no breaches were found), or rejects with an Error

Param Type Description
account string a username or email address
[options] object a configuration object
[options.apiKey] string an API key from https://haveibeenpwned.com/API/Key (default: undefined)
[options.domain] string a domain by which to filter the results (default: all domains)
[options.includeUnverified] boolean include "unverified" breaches in the results (default: true)
[options.timeoutMs] number timeout for the request in milliseconds (default: none)
[options.truncate] boolean truncate the results to only include the name of each breach (default: true)
[options.baseUrl] string a custom base URL for the haveibeenpwned.com API endpoints (default: https://haveibeenpwned.com/api/v3)
[options.userAgent] string a custom string to send as the User-Agent field in the request headers (default: hibp <version>)

Example

try {
  const data = await breachedAccount("foo", { apiKey: "my-api-key" });
  if (data) {
    // ...
  } else {
    // ...
  }
} catch (err) {
  // ...
}

Example

try {
  const data = await breachedAccount("bar", {
    includeUnverified: false,
    baseUrl: "https://my-hibp-proxy:8080",
  });
  if (data) {
    // ...
  } else {
    // ...
  }
} catch (err) {
  // ...
}

Example

try {
  const data = await breachedAccount("baz", {
    apiKey: "my-api-key",
    domain: "adobe.com",
    truncate: false,
    userAgent: "my-app 1.0",
  });
  if (data) {
    // ...
  } else {
    // ...
  }
} catch (err) {
  // ...
}

breaches([options]) ⇒ Promise.<Array.<Breach>>

Fetches all breach events in the system.

Kind: global function
Returns: Promise.<Array.<Breach>> - a Promise which resolves to an array of breach objects (an empty array if no breaches were found), or rejects with an Error

Param Type Description
[options] object a configuration object
[options.domain] string a domain by which to filter the results (default: all domains)
[options.baseUrl] string a custom base URL for the haveibeenpwned.com API endpoints (default: https://haveibeenpwned.com/api/v3)
[options.timeoutMs] number timeout for the request in milliseconds (default: none)
[options.userAgent] string a custom string to send as the User-Agent field in the request headers (default: hibp <version>)

Example

try {
  const data = await breaches();
  if (data) {
    // ...
  } else {
    // ...
  }
} catch (err) {
  // ...
}

Example

try {
  const data = await breaches({ domain: "adobe.com" });
  if (data) {
    // ...
  } else {
    // ...
  }
} catch (err) {
  // ...
}

dataClasses([options]) ⇒ Promise.<Array.<string>> | Promise.<null>

Fetches all data classes in the system.

Kind: global function
Returns: Promise.<Array.<string>> | Promise.<null> - a Promise which resolves to an array of strings (or null if no data classes were found), or rejects with an Error

Param Type Description
[options] object a configuration object
[options.baseUrl] string a custom base URL for the haveibeenpwned.com API endpoints (default: https://haveibeenpwned.com/api/v3)
[options.timeoutMs] number timeout for the request in milliseconds (default: none)
[options.userAgent] string a custom string to send as the User-Agent field in the request headers (default: hibp <version>)

Example

try {
  const data = await dataClasses();
  if (data) {
    // ...
  } else {
    // ...
  }
} catch (err) {
  // ...
}

pasteAccount(email, [options]) ⇒ Promise.<Array.<Paste>> | Promise.<null>

Fetches paste data for a specific account (email address).

🔑 haveibeenpwned.com requires an API key from https://haveibeenpwned.com/API/Key for the pasteaccount endpoint. The apiKey option here is not explicitly required, but direct requests made without it will fail (unless you specify a baseUrl to a proxy that inserts a valid API key on your behalf).

Kind: global function
Returns: Promise.<Array.<Paste>> | Promise.<null> - a Promise which resolves to an array of paste objects (or null if no pastes were found), or rejects with an Error

Param Type Description
email string the email address to query
[options] object a configuration object
[options.apiKey] string an API key from https://haveibeenpwned.com/API/Key (default: undefined)
[options.baseUrl] string a custom base URL for the haveibeenpwned.com API endpoints (default: https://haveibeenpwned.com/api/v3)
[options.timeoutMs] number timeout for the request in milliseconds (default: none)
[options.userAgent] string a custom string to send as the User-Agent field in the request headers (default: hibp <version>)

Example

try {
  const data = await pasteAccount("foo@bar.com", { apiKey: "my-api-key" });
  if (data) {
    // ...
  } else {
    // ...
  }
} catch (err) {
  // ...
}

Example

try {
  const data = await pasteAccount("foo@bar.com", {
    baseUrl: "https://my-hibp-proxy:8080",
  });
  if (data) {
    // ...
  } else {
    // ...
  }
} catch (err) {
  // ...
}

pwnedPasswordRange(prefix, [options]) ⇒ Promise.<PwnedPasswordSuffixes>

Fetches the SHA-1 or NTLM hash suffixes for the given 5-character hash prefix.

When a password hash with the same first 5 characters is found in the Pwned Passwords repository, the API will respond with an HTTP 200 and include the suffix of every hash beginning with the specified prefix, followed by a count of how many times it appears in the data set. This function parses the response and returns a more structured format.

Kind: global function
Returns: Promise.<PwnedPasswordSuffixes> - a Promise which resolves to an object mapping the suffix that when matched with the prefix composes the complete hash, to the count of how many times it appears in the breached password data set, or rejects with an Error
See: https://haveibeenpwned.com/api/v3#SearchingPwnedPasswordsByRange

Param Type Description
prefix string the first 5 characters of a password hash (case insensitive)
[options] object a configuration object
[options.addPadding] boolean ask the remote API to add padding to the response to obscure the password prefix (default: false)
[options.mode] 'sha1' | 'ntlm' return SHA-1 or NTLM hashes (default: sha1)
[options.baseUrl] string a custom base URL for the pwnedpasswords.com API endpoints (default: https://api.pwnedpasswords.com)
[options.timeoutMs] number timeout for the request in milliseconds (default: none)
[options.userAgent] string a custom string to send as the User-Agent field in the request headers (default: hibp <version>)

Example

try {
  const results = await pwnedPasswordRange("5BAA6");
  // results will have the following shape:
  // {
  //   "003D68EB55068C33ACE09247EE4C639306B": 3,
  //   "012C192B2F16F82EA0EB9EF18D9D539B0DD": 1,
  //   ...
  // }
} catch (err) {
  // ...
}

Example

try {
  const suffix = "1E4C9B93F3F0682250B6CF8331B7EE68FD8";
  const results = await pwnedPasswordRange("5BAA6");
  const numPwns = results[suffix] || 0;
} catch (err) {
  // ...
}

pwnedPassword(password, [options]) ⇒ Promise.<number>

Fetches the number of times the the given password has been exposed in a breach (0 indicating no exposure). The password is given in plain text, but only the first 5 characters of its SHA-1 hash will be submitted to the API.

Kind: global function
Returns: Promise.<number> - a Promise which resolves to the number of times the password has been exposed in a breach, or rejects with an Error
See: https://haveibeenpwned.com/api/v3#PwnedPasswords

Param Type Description
password string a password in plain text
[options] object a configuration object
[options.addPadding] boolean ask the remote API to add padding to the response to obscure the password prefix (default: false)
[options.baseUrl] string a custom base URL for the pwnedpasswords.com API endpoints (default: https://api.pwnedpasswords.com)
[options.timeoutMs] number timeout for the request in milliseconds (default: none)
[options.userAgent] string a custom string to send as the User-Agent field in the request headers (default: hibp <version>)

Example

try {
  const numPwns = await pwnedPassword("f00b4r");
  // truthy check or numeric condition
  if (numPwns) {
    // ...
  } else {
    // ...
  }
} catch (err) {
  // ...
}

search(account, [options]) ⇒ Promise.<SearchResults>

Fetches all breaches and all pastes associated with the provided account (email address or username). Note that the remote API does not support querying pastes by username (only email addresses), so in the event the provided account is not a valid email address, only breach data is queried and the "pastes" field of the resulting object will always be null. This is exactly how searching via the current web interface behaves, which this convenience method is designed to mimic.

🔑 haveibeenpwned.com requires an API key from https://haveibeenpwned.com/API/Key for the breachedaccount and pasteaccount endpoints. The apiKey option here is not explicitly required, but direct requests made without it will fail (unless you specify a baseUrl to a proxy that inserts a valid API key on your behalf).

Kind: global function
Returns: Promise.<SearchResults> - a Promise which resolves to an object containing a "breaches" key (which can be null or an array of breach objects) and a "pastes" key (which can be null or an array of paste objects), or rejects with an Error
See: https://haveibeenpwned.com/

Param Type Description
account string an email address or username
[options] object a configuration object
[options.apiKey] string an API key from https://haveibeenpwned.com/API/Key (default: undefined)
[options.domain] string a domain by which to filter the breach results (default: all domains)
[options.truncate] boolean truncate the breach results to only include the name of each breach (default: true)
[options.baseUrl] string a custom base URL for the haveibeenpwned.com API endpoints (default: https://haveibeenpwned.com/api/v3)
[options.timeoutMs] number timeout for the request in milliseconds (default: none)
[options.userAgent] string a custom string to send as the User-Agent field in the request headers (default: hibp <version>)

Example

try {
  const data = await search("foo", { apiKey: "my-api-key" });
  if (data.breaches || data.pastes) {
    // ...
  } else {
    // ...
  }
} catch (err) {
  // ...
}

Example

try {
  const data = await search("nobody@nowhere.com", {
    baseUrl: "https://my-hibp-proxy:8080",
    truncate: false,
  });
  if (data.breaches || data.pastes) {
    // ...
  } else {
    // ...
  }
} catch (err) {
  // ...
}

subscriptionStatus([options]) ⇒ Promise.<SubscriptionStatus>

Fetches the current status of your HIBP subscription (API key).

🔑 haveibeenpwned.com requires an API key from https://haveibeenpwned.com/API/Key for the subscription/status endpoint. The apiKey option here is not explicitly required, but direct requests made without it will fail (unless you specify a baseUrl to a proxy that inserts a valid API key on your behalf).

Kind: global function
Returns: Promise.<SubscriptionStatus> - a Promise which resolves to a subscription status object, or rejects with an Error

Param Type Description
[options] object a configuration object
[options.apiKey] string an API key from https://haveibeenpwned.com/API/Key (default: undefined)
[options.baseUrl] string a custom base URL for the haveibeenpwned.com API endpoints (default: https://haveibeenpwned.com/api/v3)
[options.timeoutMs] number timeout for the request in milliseconds (default: none)
[options.userAgent] string a custom string to send as the User-Agent field in the request headers (default: hibp <version>)

Example

try {
  const data = await subscriptionStatus({ apiKey: "my-api-key" });
  // ...
} catch (err) {
  // ...
}

Example

try {
  const data = await subscriptionStatus({
    baseUrl: "https://my-hibp-proxy:8080",
  });
  // ...
} catch (err) {
  // ...
}

Breach : object

An object representing a breach.

Kind: global typedef
Properties

Name Type
Name string
Title string
Domain string
BreachDate string
AddedDate string
ModifiedDate string
PwnCount number
Description string
DataClasses Array.<string>
IsVerified boolean
IsFabricated boolean
IsSensitive boolean
IsRetired boolean
IsSpamList boolean
IsMalware boolean
IsSubscriptionFree boolean
LogoPath string

Paste : object

An object representing a paste.

Kind: global typedef
Properties

Name Type
Id string
Source string
Title string
Date string
EmailCount number

PwnedPasswordSuffixes : Object.<string, number>

An object mapping an exposed password hash suffix (corresponding to a given hash prefix) to how many times it occurred in the Pwned Passwords repository.

Kind: global typedef

SearchResults : object

An object representing search results.

Kind: global typedef
Properties

Name Type
breaches Array.<Breach> | null
pastes Array.<Paste> | null

SubscriptionStatus : object

An object representing the status of your HIBP subscription.

Kind: global typedef
Properties

Name Type
SubscriptionName string
Description string
SubscribedUntil string
Rpm number
DomainSearchMaxBreachedAccounts number