|
| 1 | +# is-pwned |
| 2 | + |
| 3 | +##### Check if passwords are PWNED before they're used |
| 4 | + |
| 5 | +## Purpose |
| 6 | + |
| 7 | +[Credential stuffing](https://www.owasp.org/index.php/Credential_stuffing) is a very real threat to web application security and it's important that businesses are doing their best to protect their users from passwords that been been seen in known breaches. |
| 8 | + |
| 9 | +This library is designed to be hooked into your _login_ or _change password_ forms to ensure that users aren't using or setting passwords seen in known breaches. This is achieved by sending the first five characters of a SHA-1 copy of the user's password to [Have I Been Pwned](https://haveibeenpwned.com/API/v2)'s API and matching it against the result set that is returned. |
| 10 | + |
| 11 | +TL;DR: This adds breached password detection to input fields of your choice and has a configurable timeout so it doesn't block your login. |
| 12 | + |
| 13 | +#### Note: This library is intended for browser use only. In future versions it might support Node but the intent is to keep the library free from dependencies. |
| 14 | + |
| 15 | +## Installation |
| 16 | + |
| 17 | +Install the `is-pwned` package using `npm` or `yarn`. |
| 18 | + |
| 19 | +```bash |
| 20 | +npm i -S is-pwned |
| 21 | +``` |
| 22 | + |
| 23 | +```bash |
| 24 | +yarn add is-pwned |
| 25 | +``` |
| 26 | + |
| 27 | +### Import the Module & Configure |
| 28 | + |
| 29 | +Import the module and instantiate the class. TypeScript types are available. |
| 30 | + |
| 31 | +```typescript |
| 32 | +import IsPwned from 'is-pwned'; |
| 33 | + |
| 34 | +const pw = new IsPwned(config); |
| 35 | +``` |
| 36 | + |
| 37 | +## Methods |
| 38 | + |
| 39 | +### Check Password (`pw.check()`) |
| 40 | + |
| 41 | +pw.check returns a promise that resolves `true` or reject with an `Error`. See _Error Handling_ below. |
| 42 | + |
| 43 | +```typescript |
| 44 | +const pw = new IsPwned(config); |
| 45 | + |
| 46 | +pw.check('password'); // Promise<true> |
| 47 | +``` |
| 48 | + |
| 49 | +### Hash Password (`pw.hashPassword()`) |
| 50 | + |
| 51 | +Exposes the internal password hashing method. |
| 52 | + |
| 53 | +```typescript |
| 54 | +const pw = new IsPwned(config); |
| 55 | + |
| 56 | +pw.hashPassword('password'); // '5BAA61E4C9B93F3F0682250B6CF8331B7EE68FD8' |
| 57 | +``` |
| 58 | + |
| 59 | +## Error Handling |
| 60 | + |
| 61 | +Methods in the `is-pwned` library use custom errors so you can better handle responses. |
| 62 | + |
| 63 | +```typescript |
| 64 | +try { |
| 65 | + await pw.check('password'); |
| 66 | +} catch (e) { |
| 67 | + switch (e.name) { |
| 68 | + case 'UnexpectedHttpResponseError': |
| 69 | + // A response other than 200 was received from HIBP |
| 70 | + case 'TimedOutError': |
| 71 | + // The timeout was reached |
| 72 | + case 'InvalidPasswordError': |
| 73 | + // The password is either not a string or is empty |
| 74 | + case 'BreachedError': |
| 75 | + // The password has been breached |
| 76 | + // You can use e.count on this error type |
| 77 | + console.log(`Password has been breached ${e.count} times.`); |
| 78 | + } |
| 79 | +} |
| 80 | +``` |
| 81 | + |
| 82 | +## Configuration |
| 83 | + |
| 84 | +IsPwned can be configured accordingly: |
| 85 | + |
| 86 | +| Option | Type | Default | Purpose | |
| 87 | +| :----------------- | :------------------- | :-------------------------------------- | :---------------------------------------------- | |
| 88 | +| `endpoint` | `string` (optional) | `https://api.pwnedpasswords.com/range/` | Substitute the HIBP endpoit for your own. | |
| 89 | +| `timeout` | `number` (optional) | `5000` | Timeout on the check. | |
| 90 | +| `userAgent` | `string` (optional) | `is-pwned-js` | Change the UserAgent to represent your service. | |
| 91 | +| `resolveOnTimeout` | `boolean` (optional) | `false` | Resolve instead of erroring on timeout. | |
| 92 | + |
| 93 | +### `endpoint` |
| 94 | + |
| 95 | +In some environments a business may choose to either proxy or host their own HIBP endpoint. The script will pass the first five characters of the SHA-1'd password to the last url part — for example: `https://api.pwnedpasswords.com/range/{hash}` |
| 96 | + |
| 97 | +### `timeout` |
| 98 | + |
| 99 | +To ensure that the user experience isn't adversely affected by the additional HTTP request it is recommended to set a timeout. The default timeout is `5000` milliseconds, but you may want to change this depending on your situation. |
| 100 | + |
| 101 | +### `userAgent` |
| 102 | + |
| 103 | +The [HIBP API Acceptable Use Policy](https://haveibeenpwned.com/API/v2#AcceptableUse) requires that user agent "accurately describe the nature of the API consumer such that it can be clearly identified in the request". It is recommended that you change this, however it will default to `is-pwned-js`. |
| 104 | + |
| 105 | +Please also refer to the licensing requirements for using the [Passwords API](https://haveibeenpwned.com/API/v2#License). Accreditation isn't required but it is welcomed by HIBP. |
| 106 | + |
| 107 | +### `resolveOnTimeout` |
| 108 | + |
| 109 | +Setting this to `true` will resolve the `check` method promise if it times out which can assist in some programming situations. This is not recommended as you should try and handle this in your codebase. |
0 commit comments