npm package: @libriciel/ls-jquery-password
Description: A jQuery plugin for password fields at Libriciel SCOP, using Bootstrap 3, 4 and 5 and fork awesome. It adds a toggler and a strength meter (with respect to ANSSI recommendations) to password fields.
Author: Christian Buffin
Latest version: 1.2.3

# ls-jquery-password

## Description

A jQuery plugin for password fields at Libriciel SCOP, using Bootstrap 3, 4 or 5 and fork awesome. It adds a toggler
and a strength meter (with respect to [ANSSI recommendations](https://www.ssi.gouv.fr/administration/precautions-elementaires/calculer-la-force-dun-mot-de-passe/))
to password fields.

The strength meter was inspired by the ["_Password Strength_" xkcd comic](https://xkcd.com/936/), to encourage passwords
that humans can easily remember while still having a large entropy (possible values).

![](docs/img/description.png)

The toggler makes it possible for the user to toggle the password field to a text field so the user can check the word.

The strength meter should turn green and reach 100 % once the desired password entropy has been reached.

The strength meter __only__ takes the [entropy](https://en.wikipedia.org/wiki/Password_strength#Entropy_as_a_measure_of_password_strength)
of the password into account (brute force).

When compared to other password strength meters such as [Kaspersky password checker](https://password.kaspersky.com/en/),
it __does not__ check for repetitions, common passwords, leaked passwords, words, ...

## Basic usage

```html
<link rel="stylesheet" href="dist/css/ls-jquery-password.css">
```

```html
<script src="dist/js/ls-jquery-password.min.js"></script>
```

```js
// Example with Boostrap 4.6
$('input[type=password]')
    // Default parameters for a "strength" of 3 (entropy of at least 80) as defined by the ANSSI.
    .lsPasswordStrengthMeter($.fn.lsPasswordStrengthMeter.configure('4.6', 3))
    .lsPasswordToggler($.fn.lsPasswordToggler.configure('4.6'));
```

## Examples

| Bootstrap | jQuery | Fork awesome | Example                                                       |
| ---       | ---    | ---          | ---                                                           |
| 3.4.1     | 1.12.4 | 1.1.7        | [Bootstrap 3.4.1 example](docs/examples/bootstrap-3.4.1.html) |
| 4.6.0     | 3.5.1  | 1.1.7        | [Bootstrap 4.6.0 example](docs/examples/bootstrap-4.6.0.html) |
| 5.0.2     | 3.5.1  | 1.1.7        | [Bootstrap 5.0.2 example](docs/examples/bootstrap-5.0.2.html) |

## Advanced usage (configuration)

### lsPasswordStrengthMeter

#### Default configuration

```js
$.fn.lsPasswordStrengthMeter.configure('4.6', 3)
// which is equivalent to
{
    "className": "ls-password-strength-meter",
    "inputGroupClass": "input-group",
    "inputGroupTag": "div",
    "thresholds": [
        { "value": 0, "className": "bg-danger" },
        { "value": 40, "className": "bg-warning" },
        { "value": 80, "className": "bg-success" }
    ]
}
```

##### Result

```html
<div class="form-group row">
    <label for="UserPasswordTest" class="col-sm-3 col-form-label">Mot de passe</label>
    <div class="col-sm-9">
        <input name="data[User][password]" id="UserPasswordTest" class="form-control" type="password">
    </div>
</div>
```

```html
<div class="form-group row">
    <label for="UserPasswordTest" class="col-sm-3 col-form-label">Mot de passe</label>
    <div class="col-sm-9">
        <input name="data[User][password]" id="UserPasswordTest" class="form-control" type="password"><div class="progress ls-password-strength-meter">
            <div class="progress-bar bg-danger" role="progressbar" aria-valuenow="0" aria-valuemin="0" aria-valuemax="100" style="width:0%;">0%</div>
        </div>
    </div>
</div>
```

#### Configuration keys

| Key               | Default                      | Description                                                                                                                                                                                                                       |
| ---               | ---                          | ---                                                                                                                                                                                                                               |
| `className`       | `ls-password-strength-meter` | The `className` helps the developer target the strength meter wrapper element. The default value is also used in the _(S)CSS_ file.                                                                                               |
| `inputGroupClass` | `input-group`                | When your password input field is wrapped around an input group, its class name (Bootstrap specific, useful when used with a non default configuration for `lsPasswordToggler`).                                                  |
| `inputGroupTag`   | `div`                        | When your password input field is wrapped around an input group, its tag name (Bootstrap specific, useful when used with a non default configuration for `lsPasswordToggler`).                                                    |
| `threshold`       | `3`                          | Either a number bewteen `1` and `5` or an array containing objects with a value and a Bootstrap class name (see default below). The class name will be applied to the strength meter once the entropy threshold value is reached. |

The default `threshold` value `3` is translated to the following, when using Bootstrap 4 configuration:

```js
[
    { "value": 80, "className": "bg-success" }, // A password with an entropy >= 80 will have a 100 % green bar
    { "value": 40, "className": "bg-warning" }, // A password with an entropy >= 40 (and < 80) will have a yellow bar between [50 %, 100 % [
    { "value": 0, "className": "bg-danger" }    // A password with an entropy < 40 will have a red bar between [0 %, 50 % [
]
```

#### Thresholds

| ANSSI strength | Plugin `threshold` | Entropy threshold |
| ---            | ---                | ---               |
| Very strong    | `5`                | 128               |
| Strong         | `4`                | 100               |
| Average        | `3`                | 80                |
| Weak           | `2`                | 64                |
| Very weak      | `1`                | 1                 |

### lsPasswordToggler

#### Default configuration

```js
$.fn.lsPasswordToggler.configure('4.6')
// which is equivalent to
{
  "addonClass": "input-group-text",
  "className": "ls-password-toggler",
  "btnClasses": "btn btn-default",
  "btnWrapper": "<div class=\"input-group-prepend\"></div>",
  "hideClass": "fa-eye",
  "hideTitle": "Masquer le mot de passe",  
  "iconClass": "fa",  
  "inputGroupClass": "input-group",
  "inputGroupTag": "div",
  "position": "before",
  "showClass": "fa-eye-slash",
  "showTitle": "Afficher le mot de passe"
}
```

##### Result

```html
<div class="form-group row">
    <label for="UserPasswordTest" class="col-sm-3 col-form-label">Mot de passe</label>
    <div class="col-sm-9">
        <input name="data[User][password]" id="UserPasswordTest" class="form-control" type="password">
    </div>
</div>
```

```html
<div class="form-group row">
    <label for="UserPasswordTest" class="col-sm-3 col-form-label">Mot de passe</label>
    <div class="col-sm-9">
        <div class="input-group">
            <div class="input-group-prepend"><span class="ls-password-toggler btn btn-default input-group-text" title="Afficher le mot de passe"><span class="fa fa-eye-slash" aria-hidden="true"> </span></span>
            </div>
            <input name="data[User][password]" id="UserPasswordTest" class="form-control" type="password">
        </div>
    </div>
</div>
```

#### Configuration keys

| Key               | Default                    | Description                                                                                                                  |
| ---               | ---                        | ---                                                                                                                          |
| `addonClass`      | `input-group-addon`        | The class name that defines a Bootstrap add-on for an input field                                                            |
| `btnClasses`      | `btn btn-default`          | The Bootstrap class names used for the toggler button                                                                        |
| `className`       | `ls-password-toggler`      | The `className` helps the developer target the toggler wrapper element. The default value is also used in the _(S)CSS_ file. |
| `hideClass`       | `fa-eye-slash`             | The fork-awesome icon class for the button turning the field back into a password field                                      |
| `hideTitle`       | `Masquer le mot de passe`  | The title for the button turning the field back into a password field                                                        |
| `iconClass`       | `fa`                       | The generic fork-awesome icon class                                                                                          |
| `inputGroupClass` | `input-group`              | The class of the Bootstrap wrapper element that will be created (or already exists) around the password field                |
| `inputGroupTag`   | `div`                      | The tag of the Bootstrap wrapper element that will be created (or already exists) around the password field                  |
| `position`        | `before`                   | The add-on position with respect to the field. Accepted values are `before` or `after`.                                      |
| `showClass`       | `fa-eye`                   | The fork-awesome icon class for the button turning the field into a text field                                               |
| `showTitle`       | `Afficher le mot de passe` | The title for the button turning the field into a text field                                                                 |

## Developpment

There is a Dockerfile and a `docker-compose.yml` file that will launch a _Grunt_ that will build the dist plugin files,
launch unit tests and watch for changes made to the source code.

```bash
(docker image ls --quiet ls-jquery-password | xargs docker image rmi -f)
(docker-compose down --remove-orphans --volumes ; docker-compose up ; docker-compose down --remove-orphans --volumes)
```