feat: adding rule for sequential characters (#54)

Author: arpit-jn

README.md

@@ -114,6 +114,16 @@ Password Sheriff includes some default rules:
   });
   ```
 
+  * `sequentialChars`: Passwords should not contain more than `max` sequential (increasing or decreasing) alphanumeric characters.
+  ```js
+  var sequentialCharsPolicy = new PasswordPolicy({
+    sequentialChars: { max: 3 }
+  });
+  // 'abcd' -> false (4 sequential > 3)
+  // 'dcba' -> false (4 sequential > 3)
+  // 'abce' -> true  (sequence breaks)
+  ```
+
 See the [default-rules example](examples/default-rules.js) section for more information.
 
 ## Issue Reporting
@@ -129,4 +139,4 @@ If you have found a bug or if you have a feature request, please report them at
 This project is licensed under the MIT license. See the [LICENSE](LICENSE) file for more info.
 
 
-[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fauth0%2Fpassword-sheriff.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fauth0%2Fpassword-sheriff?ref=badge_large)
+[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fauth0%2Fpassword-sheriff.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fauth0%2Fpassword-sheriff?ref=badge_large)

examples/default-rules.js

@@ -7,6 +7,7 @@ var PasswordPolicy = require('..').PasswordPolicy;
  *  * contains
  *  * containsAtLeast
  *  * identicalChars
+ *  * sequentialChars
 */
 
 /*
@@ -101,3 +102,18 @@ assert.equal(true, identitcalCharsPolicy.check('helllo'));
 assert.equal(false, identitcalCharsPolicy.check('hellllo'));
 assert.equal(false, identitcalCharsPolicy.check('123333334'));
 
+/*
+ * sequentialChars
+ *
+ * Parameters: max :: Integer
+ *
+ * Passwords should not contain more than `max` sequential (increasing or decreasing) characters.
+ */
+var sequentialCharsPolicy = new PasswordPolicy({
+  sequentialChars: { max: 3 }
+});
+
+assert.equal(true, sequentialCharsPolicy.check('abce'));      // sequence breaks before exceeding 3
+assert.equal(true, sequentialCharsPolicy.check('cbaZ'));      // descending sequence of length 3 allowed
+assert.equal(false, sequentialCharsPolicy.check('abcd'));     // ascending length 4 not allowed
+assert.equal(false, sequentialCharsPolicy.check('dcba1'));    // descending length 4 not allowed

lib/policy.js

@@ -11,6 +11,7 @@ var defaultRuleset = {
   contains:         require('./rules/contains'),
   containsAtLeast:  require('./rules/containsAtLeast'),
   identicalChars:   require('./rules/identicalChars'),
+  sequentialChars:  require('./rules/sequentialChars')
 };
 
 function flatDescriptions (descriptions, index) {

lib/rules/sequentialChars.js

@@ -0,0 +1,145 @@
+var _ = require('../helper');
+
+/**
+ * @readonly
+ * @enum {number}
+ */
+var Direction = {
+  Ascending: 1,
+  Descending: -1,
+  None: 0
+};
+
+/**
+ * @readonly
+ * @enum {number}
+ */
+var CharacterCodes = {
+  LowerCaseA: 'a'.charCodeAt(0),
+  LowerCaseZ: 'z'.charCodeAt(0),
+  Zero: '0'.charCodeAt(0),
+  Nine: '9'.charCodeAt(0),
+  UpperCaseA: 'A'.charCodeAt(0),
+  UpperCaseZ: 'Z'.charCodeAt(0),
+};
+
+/**
+ * Determines if a character is alphanumeric
+ *
+ * @param {number} code character code
+ * @return {boolean}
+ */
+function isAlphanumeric(code) {
+  if (!_.isNumber(code) || _.isNaN(code)) {
+    return false;
+  }
+
+  if (code >= CharacterCodes.LowerCaseA && code <= CharacterCodes.LowerCaseZ) {
+    return true;
+  } else if (code >= CharacterCodes.UpperCaseA && code <= CharacterCodes.UpperCaseZ) {
+    return true;
+  } else if (code >= CharacterCodes.Zero && code <= CharacterCodes.Nine) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Returns true if password has more sequential characters the configured max allowed
+ *
+ * @param {{max: number}} options
+ * @param {string} password
+ * @return {boolean}
+ */
+function assert(options, password) {
+  if (!password) {
+    return false;
+  }
+
+  var prevCode = password.charCodeAt(0);
+  var seqLen = isAlphanumeric(prevCode) ? 1 : 0;
+  var currentDirection = Direction.None;
+
+  for (var i = 1; i < password.length; i++) {
+    var currentCode = password.charCodeAt(i);
+    if (!isAlphanumeric(currentCode) || !isAlphanumeric(prevCode)) {
+      currentDirection = Direction.None;
+      seqLen = 1;
+      prevCode = currentCode;
+      continue;
+    }
+
+    var diff = currentCode - prevCode;
+    prevCode = currentCode;
+
+    if (diff === Direction.Ascending || diff === Direction.Descending) {
+      if (currentDirection === diff) {
+        seqLen += 1;
+      } else {
+        // start a new potential sequence of length 2 (prev + current)
+        currentDirection = diff;
+        seqLen = 2;
+      }
+    } else {
+      currentDirection = Direction.None;
+      seqLen = 1;
+    }
+
+    if (seqLen > options.max) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * @param {{max: number}} options
+ * @param {boolean} verified
+ * @return {boolean}
+ */
+function explain(options, verified) {
+  var example = '';
+  for (var i = 0; i < options.max + 1; i++) {
+    example += String.fromCharCode('a'.charCodeAt(0) + i);
+  }
+  var d = {
+    message: 'No more than %d sequential alphanumeric characters (e.g., "%s" not allowed)', // updated
+    code: 'sequentialChars',
+    format: [options.max, example]
+  };
+  if (verified !== undefined) {
+    d.verified = verified;
+  }
+  return d;
+}
+
+/**
+ * @param {{max: number}} options
+ * @return {boolean}
+ */
+function validate(options) {
+  if (!_.isObject(options)) {
+    throw new Error('options should be an object');
+  }
+
+  if (!_.isNumber(options.max) || _.isNaN(options.max) || options.max < 2) {
+    throw new Error('max should be a number greater than or equal to 2');
+  }
+
+  if (!_.isNumber(options.max) || _.isNaN(options.max) || options.max > 26) {
+    throw new Error('max should be a number less than or equal to 26');
+  }
+
+  return true;
+}
+
+module.exports = {
+  validate,
+  explain,
+  missing: function (options, password) {
+    return explain(options, assert(options, password));
+  },
+  assert
+};

test/rules/sequentialChars.js

@@ -0,0 +1,134 @@
+var expect = require('chai').expect;
+
+var sequentialChars = require('../../lib/rules/sequentialChars');
+
+function sequentialCharsMessage(x, verified) {
+  var example = '';
+  for (var i = 0; i < x + 1; i++) {
+    example += String.fromCharCode('a'.charCodeAt(0) + i);
+  }
+  var msg = 'No more than %d sequential alphanumeric characters (e.g., "%s" not allowed)'; // updated wording
+  var d = {message: msg, format: [x, example], code: 'sequentialChars'};
+  if (verified !== undefined) {
+    d.verified = verified;
+  }
+  return d;
+}
+
+function sequentialCharsValidate (max) {
+  return function () {
+    return sequentialChars.validate({max: max});
+  };
+}
+
+describe('"sequential characters" rule (alphanumeric only)', function () {
+  describe('validate', function () {
+    it ('should fail if max is not a number or less than 2', function () {
+      const errorRegex = /max should be a number greater than or equal to 2/;
+
+      expect(sequentialCharsValidate(false)).to.throw(errorRegex);
+      expect(sequentialCharsValidate(0)).to.throw(errorRegex);
+      expect(sequentialCharsValidate(1)).to.throw(errorRegex);
+      expect(sequentialCharsValidate('hello')).to.throw(errorRegex);
+      expect(sequentialCharsValidate(undefined)).to.throw(errorRegex);
+    });
+
+    it('should work otherwise', function () {
+      expect(sequentialCharsValidate(2)).not.to.throw();
+      expect(sequentialCharsValidate(5)).not.to.throw();
+    });
+  });
+
+  describe('explain', function () {
+    it('should return description with message', function () {
+      expect(sequentialChars.explain({max: 3})).to.be.deep.equal(sequentialCharsMessage(3));
+    });
+  });
+
+  describe('missing', function () {
+    it('should inform that the rule is not verified for ascending sequences', function () {
+      expect(sequentialChars.missing({max: 3}, 'abcd')).to.be.deep.equal(sequentialCharsMessage(3, false));
+    });
+
+    it('should inform that the rule is not verified for descending sequences', function () {
+      expect(sequentialChars.missing({max: 3}, 'dcba')).to.be.deep.equal(sequentialCharsMessage(3, false));
+    });
+
+    it('should work otherwise', function () {
+      expect(sequentialChars.missing({max: 3}, 'abce')).to.be.deep.equal(sequentialCharsMessage(3, true));
+      expect(sequentialChars.missing({max: 3}, 'acbd')).to.be.deep.equal(sequentialCharsMessage(3, true));
+      expect(sequentialChars.missing({max: 2}, 'abc')).to.be.deep.equal(sequentialCharsMessage(2, false));
+      expect(sequentialChars.missing({max: 2}, 'abd')).to.be.deep.equal(sequentialCharsMessage(2, true));
+    });
+  });
+
+  describe('assert', function () {
+    it('should return false on ascending letters', function () {
+      expect(sequentialChars.assert({max: 2}, 'abcd')).to.be.equal(false);
+    });
+
+    it('should return false on descending letters', function () {
+      expect(sequentialChars.assert({max: 2}, 'dcba')).to.be.equal(false);
+    });
+
+    it('should return true on success for letters', function () {
+      expect(sequentialChars.assert({max: 3}, 'abce')).to.be.equal(true);
+      expect(sequentialChars.assert({max: 3}, 'acbd')).to.be.equal(true);
+      expect(sequentialChars.assert({max: 2}, 'abd')).to.be.equal(true);
+    });
+
+    it('should return false on ascending digits', function () {
+      expect(sequentialChars.assert({max: 2}, '012')).to.be.equal(false);
+    });
+
+    it('should return false on descending digits', function () {
+      expect(sequentialChars.assert({max: 2}, '654')).to.be.equal(false);
+    });
+
+    it('should return true on success for digits', function () {
+      expect(sequentialChars.assert({max: 3}, '0324')).to.be.equal(true);
+      expect(sequentialChars.assert({max: 3}, '5321')).to.be.equal(true);
+      expect(sequentialChars.assert({max: 2}, '134')).to.be.equal(true);
+    });
+  });
+
+  describe('non-alphanumeric', function () {
+    it('should treat hyphen as a break in sequence', function () {
+      expect(sequentialChars.assert({max: 2}, 'ab-cd')).to.be.equal(true); // 'ab' len2 ok, '-' break, 'cd' len2 ok
+    });
+
+    it('should treat underscore as a break in sequence', function () {
+      expect(sequentialChars.assert({max: 2}, 'ab_cd')).to.be.equal(true);
+    });
+
+    it('should break at leading non-alphanumeric', function () {
+      expect(sequentialChars.assert({max: 2}, '#ab')).to.be.equal(true); // only 'ab' len2
+    });
+
+    it('should still fail if post-break sequence exceeds max', function () {
+      expect(sequentialChars.assert({max: 2}, '#abc')).to.be.equal(false); // '#'(break) then 'abc' len3 > max
+    });
+
+    it('should allow separated digit sequences each within limit', function () {
+      expect(sequentialChars.assert({max: 2}, '01-23')).to.be.equal(true); // '01' len2 ok, '-' break, '23' len2 ok
+    });
+  });
+
+  describe('preceding non-alphanumeric with +/- 1 charCode', function () {
+    it('should not count preceding "`" (charCode 96) as part of ascending sequence starting at a (97)', function () {
+      expect(sequentialChars.assert({max: 2}, '`ab')).to.be.equal(true); // only 'ab' counted, length 2 OK
+    });
+
+    it('should fail only due to actual sequence after break, not including preceding "`"', function () {
+      expect(sequentialChars.assert({max: 2}, '`abc')).to.be.equal(false); // 'abc' len3 > max; '`' ignored
+    });
+
+    it('should not count preceding "{" (charCode 123) as part of descending sequence starting at z (122)', function () {
+      expect(sequentialChars.assert({max: 2}, '{zy')).to.be.equal(true); // 'zy' len2 OK
+    });
+
+    it('should fail when descending sequence after break exceeds max, excluding preceding "{"', function () {
+      expect(sequentialChars.assert({max: 2}, '{zyx')).to.be.equal(false); // 'zyx' len3 > max
+    });
+  });
+});