password-sheriff - npm Package Compare versions

Comparing version 1.0.0 to 1.0.1

examples/custom-rule.js

 var assert = require('assert');
-
 var format = require('util').format;
 
+var PasswordPolicy = require('..').PasswordPolicy;
+
 // Custom rules
@@ -49,3 +50,3 @@
 FooRule.prototype.missing = function (options, password) {
-  var explain = this.explain();
+  var explain = this.explain(options);
   explain.verified = this.assert(options, password);
@@ -52,0 +53,0 @@ return explain;

index.js

@@ -103,2 +103,4 @@
 
+module.exports.charsets = charsets;
+
 // module.exports.rulesToApply = rulesToApply;

package.json

 {
   "name": "password-sheriff",
   "description": "Password policy checker/enforcer.",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "main": "index.js",
@@ -6,0 +6,0 @@ "devDependencies": {

README.md

 # Password Sheriff
 
-Password policy enforcer.
+Node.js (and browserify supported) library to enforce password policies.
 
@@ -14,28 +14,102 @@ ## Install
 ```js
-var createPolicy = require('password-sheriff');
-var policy = createPolicy('good');
+var PasswordPolicy = require('password-sheriff').PasswordPolicy;
 
-// Creates a password policy based on OWASP password recommendations
-var policyOWASP = createPolicy('excellent');
+// Create a length password policy
+var lengthPolicy = new PasswordPolicy({length: {minLength: 6}});
 
-// Displays the following password criteria:
-// * 8 characters in length
-// * contain at least 3 of the following 4 types of characters:
-//  * lower case letters (a-z),
-//  * upper case letters (A-Z),
-//  * numbers (i.e. 0-9),
-//  * special characters (e.g. !@#$%^&*)
-console.log(policy.toString());
+// will throw as the password does not meet criteria
+lengthPolicy.assert('hello');
 
-// returns false, it does not meet requirements
-policy.check('hello');
-policy.check('helloAD');
+// returns false if password does not meet rules
+assert.equal(false, lengthPolicy.check('hello'));
 
-// returns true
-policy.check('helloA1S2D1');
+// explains the policy
+var explained = lengthPolicy.explain();
 
-// asserts a password (throws an exception if invalid)
-policy.assert('hello');
+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 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('../lib/rules/containsAtLeast').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
@@ -45,1 +119,8 @@
 
+## Author
+
+[Auth0](auth0.com)
+
+## License
+
+This project is licensed under the MIT license. See the [LICENSE](LICENSE) file for more info.

Fixed alerts

Debug access

Supply chain risk

Uses debug, reflection and dynamic code execution features.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

59256

14.8%

Number of package files

27

8%

Lines of code

1272

10.42%

Number of lines in readme file

125

184.09%

Number of low supply chain risk alerts

1

-50%

No dependency changes