@triangular/password-checker

Angular Pwned Password Checker Directive

Protect your users from re-using a password known to be hacked with this simple Angular directive. Check out the example page to see how it works. The passwords never leave the browser memory and are not transmitted over the network.

Getting Started

If you just want to use the library to verify the passwords given by your users, follow the following 4 simple steps. For contributing, or building the library locally, see the section on building the library.

Supported Angular Versions

Angular Version	Password Checker Version
6.x	1.0.0
7.x	2.2.0
8.x	3.0.0
9.x	4.0.0
10.x	5.0.0
11.x	6.0.0
12.x	7.0.0
13.x	8.0.1
14.x	9.0.0
15.x	10.0.0
16.x	11.0.0
17.x	12.0.0
18.x	13.0.0 - 13.2.0
19.x	14.0.0

Step 1: Install

Install the npm package.

npm i @triangular/password-checker

Step 2: Add to NgModule Imports

Then, add the PasswordCheckerModule to the imports of your app.

If you're using standalone components, you can skip this step.

import { NgModule } from '@angular/core';
import { PasswordCheckerModule } from '@triangular/password-checker';

@NgModule({
    declarations: [
    ],
    imports: [
      PasswordCheckerModule,
    ],
    providers: [],
    bootstrap: [],
})
export class AppModule { }

Step 3: Add Directive to an Input

Now you can use the provided directive pwnedPasswordValidator on your reactive forms, to trigger the validation with the pwned password database whenever the form is being validated.

<input
  pwnedPasswordValidator
  formControlName="password"
  type="password"
>

You can configure the directive by providing additional input bindings. Currently the API endpoint, the input debounce time, as well as the minimum occurrence of a password to fail the validation are configurable:

<input
  pwnedPasswordValidator
  pwnedPasswordMinimumOccurrenceForError="1"
  pwnedPasswordApi="https://api.pwnedpasswords.com/range/"
  pwnedPasswordApiCallDebounceTime="400"
  formControlName="password"
  type="password"
>

Alternatively, you can configure your module by using the PasswordCheckerModule.forRoot() method.

@NgModule({
  declarations: [
    AppComponent,
    ExampleComponent,
  ],
  imports: [
    BrowserModule,
    FormsModule,
    ReactiveFormsModule,
    PasswordCheckerModule.forRoot( {
      pwnedPasswordApiCallDebounceTime: 1000,
      pwnedPasswordMinimumOccurrenceForError: 4,
      pwnedPasswordApi: 'https://api.pwnedpasswords.com/range/',
    }),
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

Step 4: Provide Feedback

Don't forget to provide some feedback to your users:

<div
*ngIf="!form.get('password').pending && form.get('password').errors && form.get('password').errors.pwnedPasswordOccurrence"
class="invalid-feedback">
  <h2>This password has been seen 
  <span class="invalid-feedback--highlight">
  {{form.get('password').errors.pwnedPasswordOccurrence | number:'1.0-0' }}
  </span>
   times before</h2>
  <p>This password has previously appeared in a data breach and should never be used.
  If you've ever used it anywhere before, change it!
  </p>
</div>

Building

As a pre-requisite to build the library, you need to install all the dependencies via npm install or yarn.

Building the Library

Before the sample app can be run, you need to build the library itself.

npm run ng -- build password-checker-lib --progress=false

Building the Sample App

After building the library, it is either possible to build the sample app, via

npm run ng -- build example-app --prod --progress=false

,or to run the sample app with a local dev server:

npm run ng -- serve

Running the tests

Unit Tests

There are not many tests, but those that are can be run with:

npm run test -- --no-watch --progress=false --code-coverage --browsers ChromeHeadless

And coding style tests

The project follows the angular style guide and lints with the following command:

npm run lint

Built With

• Angular - The web framework used
• NPM - Dependency Management
• Gitlab - Source Control & CI Runner

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Versioning

We use SemVer for versioning.

Authors

• Raphael Ochsenbein - Initial work - Akehir

See also the list of contributors who participated in this project.

License

This project is licensed under the MIT License - see the LICENSE.md file for details

Acknowledgments

• Pwned Passwords for providing the API
• CloudFlare For sponsoring the hosting of the API
• angularindepth for a tutorial for creating an angular library
• PurpleBooth for the readme template