hibp 0.0.0-dev.8859c6fb

package/dist/hibp.d.ts

@@ -0,0 +1,502 @@
+// Generated by dts-bundle-generator v7.2.0
+
+//
+// Data Models from the API
+//
+export interface Breach {
+  Name: string;
+  Title: string;
+  Domain: string;
+  BreachDate: string;
+  AddedDate: string;
+  ModifiedDate: string;
+  PwnCount: number;
+  Description: string;
+  LogoPath: string;
+  DataClasses: string[];
+  IsVerified: boolean;
+  IsFabricated: boolean;
+  IsSensitive: boolean;
+  IsRetired: boolean;
+  IsSpamList: boolean;
+}
+export interface Paste {
+  Id: string;
+  Source: string;
+  Title: string;
+  Date: string;
+  EmailCount: number;
+}
+/**
+ * An object representing a breach.
+ *
+ * @typedef {object} Breach
+ * @property {string} Name
+ * @property {string} Title
+ * @property {string} Domain
+ * @property {string} BreachDate
+ * @property {string} AddedDate
+ * @property {string} ModifiedDate
+ * @property {number} PwnCount
+ * @property {string} Description
+ * @property {string} LogoPath
+ * @property {string[]} DataClasses
+ * @property {boolean} IsVerified
+ * @property {boolean} IsFabricated
+ * @property {boolean} IsSensitive
+ * @property {boolean} IsRetired
+ * @property {boolean} IsSpamList
+ */
+/**
+ * Fetches data for a specific breach event.
+ *
+ * @param {string} breachName the name of a breach in the system
+ * @param {object} [options] a configuration object
+ * @param {string} [options.baseUrl] a custom base URL for the
+ * haveibeenpwned.com API endpoints (default:
+ * `https://haveibeenpwned.com/api/v3`)
+ * @param {string} [options.userAgent] a custom string to send as the User-Agent
+ * field in the request headers (default: `hibp <version>`)
+ * @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
+ * @example
+ * breach('Adobe')
+ *   .then(data => {
+ *     if (data) {
+ *       // ...
+ *     } else {
+ *       // ...
+ *     }
+ *   })
+ *   .catch(err => {
+ *     // ...
+ *   });
+ */
+export declare function breach(
+  breachName: string,
+  options?: {
+    baseUrl?: string;
+    userAgent?: string;
+  },
+): Promise<Breach | null>;
+/**
+ * Fetches breach data for a specific account.
+ *
+ * ***Warning (July 18, 2019):***
+ *
+ * `haveibeenpwned.com` now 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 (that is, without specifying a `baseUrl` to a proxy that inserts a
+ * valid API key on your behalf) will fail.
+ *
+ * @param {string} account a username or email address
+ * @param {object} [options] a configuration object
+ * @param {string} [options.apiKey] an API key from
+ * https://haveibeenpwned.com/API/Key (default: undefined)
+ * @param {string} [options.domain] a domain by which to filter the results
+ * (default: all domains)
+ * @param {boolean} [options.includeUnverified] include "unverified" breaches in
+ * the results (default: true)
+ * @param {boolean} [options.truncate] truncate the results to only include
+ * the name of each breach (default: true)
+ * @param {string} [options.baseUrl] a custom base URL for the
+ * haveibeenpwned.com API endpoints (default:
+ * `https://haveibeenpwned.com/api/v3`)
+ * @param {string} [options.userAgent] a custom string to send as the User-Agent
+ * field in the request headers (default: `hibp <version>`)
+ * @returns {(Promise<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
+ * @example
+ * breachedAccount('foo', { apiKey: 'my-api-key' })
+ *   .then(data => {
+ *     if (data) {
+ *       // ...
+ *     } else {
+ *       // ...
+ *     }
+ *   })
+ *   .catch(err => {
+ *     // ...
+ *   });
+ * @example
+ * breachedAccount('bar', {
+ *   includeUnverified: false,
+ *   baseUrl: 'https://my-hibp-proxy:8080',
+ * })
+ *   .then(data => {
+ *     if (data) {
+ *       // ...
+ *     } else {
+ *       // ...
+ *     }
+ *   })
+ *   .catch(err => {
+ *     // ...
+ *   });
+ * @example
+ * breachedAccount('baz', {
+ *   apiKey: 'my-api-key',
+ *   domain: 'adobe.com',
+ *   truncate: false,
+ *   userAgent: 'my-app 1.0'
+ * })
+ *   .then(data => {
+ *     if (data) {
+ *       // ...
+ *     } else {
+ *       // ...
+ *     }
+ *   })
+ *   .catch(err => {
+ *     // ...
+ *   });
+ */
+export declare function breachedAccount(
+  account: string,
+  options?: {
+    apiKey?: string;
+    domain?: string;
+    includeUnverified?: boolean;
+    truncate?: boolean;
+    baseUrl?: string;
+    userAgent?: string;
+  },
+): Promise<Breach[] | null>;
+/**
+ * Fetches all breach events in the system.
+ *
+ * @param {object} [options] a configuration object
+ * @param {string} [options.domain] a domain by which to filter the results
+ * (default: all domains)
+ * @param {string} [options.baseUrl] a custom base URL for the
+ * haveibeenpwned.com API endpoints (default:
+ * `https://haveibeenpwned.com/api/v3`)
+ * @param {string} [options.userAgent] a custom string to send as the User-Agent
+ * field in the request headers (default: `hibp <version>`)
+ * @returns {Promise<Breach[]>} a Promise which resolves to an array of breach
+ * objects (an empty array if no breaches were found), or rejects with an Error
+ * @example
+ * breaches()
+ *   .then(data => {
+ *     if (data) {
+ *       // ...
+ *     } else {
+ *       // ...
+ *     }
+ *   })
+ *   .catch(err => {
+ *     // ...
+ *   });
+ * @example
+ * breaches({ domain: 'adobe.com' })
+ *   .then(data => {
+ *     if (data) {
+ *       // ...
+ *     } else {
+ *       // ...
+ *     }
+ *   })
+ *   .catch(err => {
+ *     // ...
+ *   });
+ */
+export declare function breaches(options?: {
+  domain?: string;
+  baseUrl?: string;
+  userAgent?: string;
+}): Promise<Breach[]>;
+/**
+ * Fetches all data classes in the system.
+ *
+ * @param {object} [options] a configuration object
+ * @param {string} [options.baseUrl] a custom base URL for the
+ * haveibeenpwned.com API endpoints (default:
+ * `https://haveibeenpwned.com/api/v3`)
+ * @param {string} [options.userAgent] a custom string to send as the User-Agent
+ * field in the request headers (default: `hibp <version>`)
+ * @returns {(Promise<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
+ * @example
+ * dataClasses()
+ *   .then(data => {
+ *     if (data) {
+ *       // ...
+ *     } else {
+ *       // ...
+ *     }
+ *   })
+ *   .catch(err => {
+ *     // ...
+ *   });
+ */
+export declare function dataClasses(options?: {
+  baseUrl?: string;
+  userAgent?: string;
+}): Promise<string[] | null>;
+/**
+ * An object representing a paste.
+ *
+ * @typedef {object} Paste
+ * @property {string} Id
+ * @property {string} Source
+ * @property {string} Title
+ * @property {string} Date
+ * @property {number} EmailCount
+ */
+/**
+ * Fetches paste data for a specific account (email address).
+ *
+ * ***Warning (July 18, 2019):***
+ *
+ * `haveibeenpwned.com` now 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 (that is, without specifying a `baseUrl` to a proxy that inserts a
+ * valid API key on your behalf) will fail.
+ *
+ * @param {string} email the email address to query
+ * @param {object} [options] a configuration object
+ * @param {string} [options.apiKey] an API key from
+ * https://haveibeenpwned.com/API/Key
+ * @param {string} [options.baseUrl] a custom base URL for the
+ * haveibeenpwned.com API endpoints (default:
+ * `https://haveibeenpwned.com/api/v3`)
+ * @param {string} [options.userAgent] a custom string to send as the User-Agent
+ * field in the request headers (default: `hibp <version>`)
+ * @returns {(Promise<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
+ * @example
+ * pasteAccount('foo@bar.com', { apiKey: 'my-api-key' })
+ *   .then(data => {
+ *     if (data) {
+ *       // ...
+ *     } else {
+ *       // ...
+ *     }
+ *   })
+ *   .catch(err => {
+ *     // ...
+ *   });
+ */
+export declare function pasteAccount(
+  email: string,
+  options?: {
+    apiKey?: string;
+    baseUrl?: string;
+    userAgent?: string;
+  },
+): Promise<Paste[] | null>;
+/**
+ * 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.
+ *
+ * @param {string} password a password in plain text
+ * @param {object} [options] a configuration object
+ * @param {string} [options.baseUrl] a custom base URL for the
+ * pwnedpasswords.com API endpoints (default: `https://api.pwnedpasswords.com`)
+ * @param {string} [options.userAgent] a custom string to send as the User-Agent
+ * field in the request headers (default: `hibp <version>`)
+ * @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
+ * @example
+ * pwnedPassword('f00b4r')
+ *   .then(numPwns => {
+ *     // truthy check or numeric condition
+ *     if (numPwns) {
+ *       // ...
+ *     } else {
+ *       // ...
+ *     }
+ *   })
+ *   .catch(err => {
+ *     // ...
+ *   });
+ * @see https://haveibeenpwned.com/api/v3#PwnedPasswords
+ */
+export declare function pwnedPassword(
+  password: string,
+  options?: {
+    baseUrl?: string;
+    userAgent?: string;
+  },
+): Promise<number>;
+export interface PwnedPasswordSuffixes {
+  [suffix: 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.
+ *
+ * @typedef {Object.<string, number>} PwnedPasswordSuffixes
+ */
+/**
+ * Fetches the SHA-1 hash suffixes for the given 5-character SHA-1 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.
+ *
+ * @param {string} prefix the first 5 characters of a SHA-1 password hash (case
+ * insensitive)
+ * @param {object} [options] a configuration object
+ * @param {string} [options.baseUrl] a custom base URL for the
+ * pwnedpasswords.com API endpoints (default: `https://api.pwnedpasswords.com`)
+ * @param {string} [options.userAgent] a custom string to send as the User-Agent
+ * field in the request headers (default: `hibp <version>`)
+ * @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
+ *
+ * @example
+ * pwnedPasswordRange('5BAA6')
+ *   .then(results => {
+ *     // results will have the following shape:
+ *     // {
+ *     //   "003D68EB55068C33ACE09247EE4C639306B": 3,
+ *     //   "012C192B2F16F82EA0EB9EF18D9D539B0DD": 1,
+ *     //   ...
+ *     // }
+ *   })
+ * @example
+ * const suffix = '1E4C9B93F3F0682250B6CF8331B7EE68FD8';
+ * pwnedPasswordRange('5BAA6')
+ *   .then(results => (results[suffix] || 0))
+ *   .catch(err => {
+ *     // ...
+ *   });
+ * @see https://haveibeenpwned.com/api/v3#SearchingPwnedPasswordsByRange
+ */
+export declare function pwnedPasswordRange(
+  prefix: string,
+  options?: {
+    baseUrl?: string;
+    userAgent?: string;
+  },
+): Promise<PwnedPasswordSuffixes>;
+export interface SearchResults {
+  breaches: Breach[] | null;
+  pastes: Paste[] | null;
+}
+/**
+ * An object representing search results.
+ *
+ * @typedef {object} SearchResults
+ * @property {(Breach[] | null)} breaches
+ * @property {(Paste[] | null)} pastes
+ */
+/**
+ * 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.
+ *
+ * ***Warning (July 18, 2019):***
+ *
+ * `haveibeenpwned.com` now 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 (that is, without specifying a
+ * `baseUrl` to a proxy that inserts a valid API key on your behalf) will fail.
+ *
+ * @param {string} account an email address or username
+ * @param {object} [breachOptions] a configuration object pertaining to breach
+ * queries
+ * @param {string} [breachOptions.apiKey] an API key from
+ * https://haveibeenpwned.com/API/Key
+ * @param {string} [breachOptions.domain] a domain by which to filter the
+ * results (default: all domains)
+ * @param {boolean} [breachOptions.truncate] truncate the results to only
+ * include the name of each breach (default: true)
+ * @param {string} [breachOptions.baseUrl] a custom base URL for the
+ * haveibeenpwned.com API endpoints (default:
+ * `https://haveibeenpwned.com/api/v3`)
+ * @param {string} [breachOptions.userAgent] a custom string to send as the
+ * User-Agent field in the request headers (default: `hibp <version>`)
+ * @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
+ * @example
+ * search('foo', { apiKey: 'my-api-key' })
+ *   .then(data => {
+ *     if (data.breaches || data.pastes) {
+ *       // ...
+ *     } else {
+ *       // ...
+ *     }
+ *   })
+ *   .catch(err => {
+ *     // ...
+ *   });
+ * @example
+ * search('nobody@nowhere.com', { apiKey: 'my-api-key', truncate: false })
+ *   .then(data => {
+ *     if (data.breaches || data.pastes) {
+ *       // ...
+ *     } else {
+ *       // ...
+ *     }
+ *   })
+ *   .catch(err => {
+ *     // ...
+ *   });
+ *
+ * @see https://haveibeenpwned.com/
+ */
+export declare function search(
+  account: string,
+  breachOptions?: {
+    apiKey?: string;
+    domain?: string;
+    truncate?: boolean;
+    baseUrl?: string;
+    userAgent?: string;
+  },
+): Promise<SearchResults>;
+/**
+ * Custom error thrown when the haveibeenpwned.com API responds with 429 Too
+ * Many Requests. See the `retryAfterSeconds` property for the number of seconds
+ * to wait before attempting the request again.
+ *
+ * @see https://haveibeenpwned.com/API/v3#RateLimiting
+ */
+export declare class RateLimitError extends Error {
+  /**
+   * The number of seconds to wait before attempting the request again. May be
+   * `undefined` if the API does not provide a `retry-after` header, but this
+   * should never happen.
+   */
+  retryAfterSeconds: number | undefined;
+  constructor(
+    retryAfter: ReturnType<Headers['get']>,
+    message: string | undefined,
+    options?: ErrorOptions,
+  );
+}
+export interface HIBP {
+  breach: typeof breach;
+  breachedAccount: typeof breachedAccount;
+  breaches: typeof breaches;
+  dataClasses: typeof dataClasses;
+  pasteAccount: typeof pasteAccount;
+  pwnedPassword: typeof pwnedPassword;
+  pwnedPasswordRange: typeof pwnedPasswordRange;
+  search: typeof search;
+  RateLimitError: typeof RateLimitError;
+}
+
+export as namespace hibp;
+
+export {};

package/example/runkit.js

@@ -0,0 +1,16 @@
+const hibp = require('hibp');
+
+hibp
+  .breach('Adobe')
+  .then((data) => {
+    if (data) {
+      // Breach data found
+      console.log(data);
+    } else {
+      console.log('No breach data found by that name.');
+    }
+  })
+  .catch((err) => {
+    // Something went wrong.
+    console.log(err.message);
+  });

package/package.json

@@ -0,0 +1,138 @@
+{
+  "name": "hibp",
+  "version": "0.0.0-dev.8859c6fb",
+  "description": "A Promise-based client for the 'Have I been pwned?' service.",
+  "keywords": [
+    "haveibeenpwned",
+    "hibp",
+    "pwned",
+    "security",
+    "hack",
+    "dump",
+    "breach",
+    "pastes",
+    "passwords",
+    "client"
+  ],
+  "author": {
+    "name": "Justin Hall",
+    "email": "justin.r.hall@gmail.com"
+  },
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/hibp.d.ts",
+      "browser": "./dist/browser/hibp.module.js",
+      "umd": "./dist/browser/hibp.umd.js",
+      "require": "./dist/cjs/hibp.js",
+      "import": "./dist/esm/hibp.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "dist/cjs/hibp.js",
+  "module": "dist/esm/hibp.mjs",
+  "unpkg": "dist/browser/hibp.umd.js",
+  "types": "dist/hibp.d.ts",
+  "runkitExampleFilename": "example/runkit.js",
+  "files": [
+    "dist",
+    "example",
+    "API.md",
+    "CHANGELOG.md",
+    "MIGRATION.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "run-s --silent build:bundle build:types build:docs",
+    "build:bundle": "rollup --config",
+    "build:docs": "jsdoc2md --no-cache --files src/*.ts --configure jsdoc2md.json > API.md && node scripts/fix-api-docs.js",
+    "build:types": "dts-bundle-generator --silent --umd-module-name hibp --out-file dist/hibp.d.ts src/hibp.ts && prettier --loglevel silent --write dist/hibp.d.ts",
+    "changeset": "changeset",
+    "changeset:version": "changeset version && npm install --package-lock-only",
+    "changeset:publish": "changeset publish",
+    "check-types": "run-p --silent check-types:*",
+    "check-types:cypress": "tsc --project cypress",
+    "check-types:src": "tsc --noEmit",
+    "clean": "rimraf dist coverage",
+    "cy:open": "cypress open",
+    "cy:run": "cypress run",
+    "format": "prettier --cache --write .",
+    "lint": "eslint .",
+    "prebuild": "npm run --silent clean",
+    "prepare": "npm run --silent build",
+    "size": "bundlewatch --config .bundlewatch.config.js",
+    "ssat": "start-server-and-test start-test-server 3000",
+    "start-test-server": "serve --no-clipboard",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:browser:open": "run-s --silent build:bundle \"ssat cy:open\"",
+    "test:browser:run": "run-s --silent build:bundle \"ssat cy:run\"",
+    "test:watch": "vitest watch"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wKovacs64/hibp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/wKovacs64/hibp/issues"
+  },
+  "homepage": "https://wkovacs64.github.io/hibp",
+  "engines": {
+    "node": ">= 12.16"
+  },
+  "dependencies": {
+    "@remix-run/web-fetch": "4.3.2",
+    "jssha": "^3.3.0"
+  },
+  "devDependencies": {
+    "@babel/core": "7.20.12",
+    "@babel/parser": "7.20.13",
+    "@babel/plugin-proposal-class-properties": "7.18.6",
+    "@babel/plugin-proposal-object-rest-spread": "7.20.7",
+    "@babel/preset-env": "7.20.2",
+    "@babel/preset-typescript": "7.18.6",
+    "@changesets/changelog-github": "0.4.8",
+    "@changesets/cli": "2.26.0",
+    "@rollup/plugin-babel": "6.0.3",
+    "@rollup/plugin-commonjs": "24.0.1",
+    "@rollup/plugin-json": "6.0.0",
+    "@rollup/plugin-node-resolve": "15.0.1",
+    "@rollup/plugin-replace": "5.0.2",
+    "@rollup/plugin-terser": "0.4.0",
+    "@rollup/plugin-typescript": "11.0.0",
+    "@types/common-tags": "1.8.1",
+    "@types/debug": "4.1.7",
+    "@types/node": "16.18.11",
+    "@types/ws": "8.5.4",
+    "@vitest/coverage-c8": "0.28.3",
+    "@wkovacs64/prettier-config": "3.0.3",
+    "babel-plugin-annotate-pure-calls": "0.4.0",
+    "bundlewatch": "0.3.3",
+    "c8": "7.12.0",
+    "codecov": "3.8.3",
+    "common-tags": "1.8.2",
+    "cross-env": "7.0.3",
+    "cypress": "12.4.1",
+    "dts-bundle-generator": "7.2.0",
+    "eslint": "8.33.0",
+    "eslint-plugin-cypress": "2.12.1",
+    "eslint-plugin-wkovacs64": "14.1.0",
+    "glob": "8.1.0",
+    "jsdoc-babel": "0.5.0",
+    "jsdoc-to-markdown": "8.0.0",
+    "msw": "1.0.0",
+    "npm-run-all": "4.1.5",
+    "prettier": "2.8.3",
+    "rimraf": "4.1.2",
+    "rollup": "3.12.0",
+    "serve": "14.2.0",
+    "start-server-and-test": "1.15.3",
+    "tslib": "2.5.0",
+    "typescript": "4.9.4",
+    "vitest": "0.28.3"
+  }
+}