https://github.com/auth0/password-sheriff
Password policies made easy.
https://github.com/auth0/password-sheriff
dx-sdk
Last synced: about 1 year ago
JSON representation
Password policies made easy.
- Host: GitHub
- URL: https://github.com/auth0/password-sheriff
- Owner: auth0
- License: other
- Created: 2014-05-19T16:28:36.000Z (about 12 years ago)
- Default Branch: master
- Last Pushed: 2025-03-28T17:46:38.000Z (about 1 year ago)
- Last Synced: 2025-04-12T16:47:41.427Z (about 1 year ago)
- Topics: dx-sdk
- Language: JavaScript
- Homepage:
- Size: 131 KB
- Stars: 76
- Watchers: 64
- Forks: 20
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
- awesome-auth0 - password-sheriff - Node.js library to enforce password policies. (Developer Ecosystem)
README
# Password Sheriff
[](https://app.fossa.com/projects/git%2Bgithub.com%2Fauth0%2Fpassword-sheriff?ref=badge_shield)
Node.js (and browserify supported) library to enforce password policies.
## Install
```sh
npm install password-sheriff
```
## Usage
```js
var PasswordPolicy = require('password-sheriff').PasswordPolicy;
// Create a length password policy
var lengthPolicy = new PasswordPolicy({length: {minLength: 6}});
// will throw as the password does not meet criteria
lengthPolicy.assert('hello');
// returns false if password does not meet rules
assert.equal(false, lengthPolicy.check('hello'));
// explains the policy
var explained = lengthPolicy.explain();
assert.equal(1, explained.length);
// easier i18n
assert.equal('lengthAtLeast', explained[0].code);
assert.equal('At least 6 characters in length',
format(explained[0].message, explained[0].format));
```
### API
#### Password Rules
Password Rules are objects that implement the following methods:
* `rule.validate(options)`: method called after the rule was created in order to validate `options` arguments.
* `rule.assert(options, password)`: returns true if `password` is valid.
* `rule.explain(options)`: returns an object with `code`, `message` and `format` attributes:
* `code`: Identifier of the rule. This attribute is meant to aid i18n.
* `message`: Description of the rule that must be formatted using `util.format`.
* `format`: Array of `string` or `Number` that will be used for the replacements required in `message`.
* `rule.missing(options, password)`: returns an object similar to `rule.explain` plus an additional field `verified` that informs whether the password meets the rule.
Example of `rule.explain` method:
```js
FooRule.prototype.explain = function (options) {
return {
// identifier rule (to make i18n easier)
code: 'foo',
message: 'Foo should be present at least %d times.',
format: [options.count]
};
};
```
When explained:
```js
var explained = fooRule.explain({count: 5});
// "Foo should be present at least 5 times"
util.format(explained.message, explained.format[0]);
```
See the [custom-rule example](examples/custom-rule.js) section for more information.
#### Built-in Password Rules
Password Sheriff includes some default rules:
* `length`: The minimum amount of characters a password must have.
```js
var lengthPolicy = new PasswordPolicy({length: {minLength: 3}});
```
* `contains`: Password should contain all of the charsets specified. There are 4 predefined charsets: `upperCase`, `lowerCase`, `numbers` and `specialCharacters` (`specialCharacters`are the ones defined in OWASP Password Policy recommendation document).
```js
var charsets = require('password-sheriff').charsets;
var containsPolicy = new PasswordPolicy({contains: {
expressions: [charsets.upperCase, charsets.numbers]
}});
```
* `containsAtLeast`: Passwords should contain at least `atLeast` of a total of `expressions.length` groups.
```js
var charsets = require('password-sheriff').charsets;
var containsAtLeastPolicy = new PasswordPolicy({
containsAtLeast: {
atLeast: 2,
expressions: [ charsets.lowerCase, charsets.upperCase, charsets.numbers ]
}
});
```
* `identicalChars`: Passwords should not contain any character repeated continuously `max + 1` times.
```js
var identitcalCharsPolicy = new PasswordPolicy({
identicalChars: {
max: 3
}
});
```
See the [default-rules example](examples/default-rules.js) section for more information.
## Issue Reporting
If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. The [Responsible Disclosure Program](https://auth0.com/whitehat) details the procedure for disclosing security issues.
## Author
[Auth0](https://auth0.com)
## License
This project is licensed under the MIT license. See the [LICENSE](LICENSE) file for more info.
[](https://app.fossa.com/projects/git%2Bgithub.com%2Fauth0%2Fpassword-sheriff?ref=badge_large)