auth0-password-policies 1.0.2 → 1.1.1

package/.github/workflows/publish.yml

@@ -0,0 +1,100 @@
+name: Test and Publish
+
+
+on:
+  push:
+    branches: [ master ]
+    tags: [ 'v*' ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [16.x, 18.x, 20.x]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@ff7abcd0c3c05ccf6adc123a8cd1fd4fb30fb493 # Aug 2025
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@5e2628c959b9ade56971c0afcebbe5332d44b398 # Aug 2025
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'yarn'
+
+      - name: Install dependencies
+        run: yarn install
+
+      - name: Run tests
+        run: yarn test
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: test
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@ff7abcd0c3c05ccf6adc123a8cd1fd4fb30fb493 # Aug 2025
+
+      - name: Verify tag is on master branch
+        shell: bash
+        run: |
+
+          git fetch origin master
+
+          # Check if the current commit (tag) is reachable from master
+          if ! git merge-base --is-ancestor HEAD origin/master; then
+            echo "Error: Tag ${{ github.ref_name }} is not on the master branch"
+            echo "Tags can only be published from commits that exist on master"
+            exit 1
+          fi
+          echo "✅ Tag ${{ github.ref_name }} is on master branch"
+
+      - name: Validate tag format
+        shell: bash
+        run: |
+          TAG=${GITHUB_REF#refs/tags/}
+          echo "Publishing tag: $TAG"
+          if [[ ! $TAG =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-beta(\.[0-9]+)?)?$ ]]; then
+            echo "Invalid tag format. Expected: v1.2.3 or v1.2.3-beta or v1.2.3-beta.1"
+            exit 1
+          fi
+
+      - name: Setup Node
+        uses: actions/setup-node@5e2628c959b9ade56971c0afcebbe5332d44b398 # Aug 2025
+        with:
+          node-version: 20
+          cache: 'yarn'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        shell: bash
+        run: yarn install --frozen-lockfile
+
+      - name: Determine npm tag
+        id: npm-tag
+        shell: bash
+        run: |
+          TAG="${GITHUB_REF#refs/tags/}"
+          if [[ "$TAG" == *"-beta"* ]]; then
+            echo "tag=beta" >> $GITHUB_OUTPUT
+            echo "Publishing as beta release"
+          else
+            echo "tag=latest" >> $GITHUB_OUTPUT
+            echo "Publishing as latest release"
+          fi
+
+      - name: Publish release to NPM
+        shell: bash
+        run: |
+          echo "About to run: npm publish --provenance --tag ${{ steps.npm-tag.outputs.tag }}"
+          npm publish --provenance --tag ${{ steps.npm-tag.outputs.tag }}
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/CODEOWNERS

@@ -0,0 +1,2 @@
+# Code owners are automatically requested for review when someone opens a pull request that modifies code that they own.
+*    @auth0/project-iam-user-management-engineer-codeowner

package/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+
+# Contributing to Auth0 projects
+
+A big welcome and thank you for considering contributing to the Auth0 projects. It’s people like you that make it a reality for users in our community.
+
+Reading and following these guidelines will help us make the contribution process easy and effective for everyone involved. It also communicates that you agree to respect the time of the developers managing and developing these open source projects. In return, we will reciprocate that respect by addressing your issue.
+
+### Quicklinks
+
+* [Code of Conduct](#code-of-conduct)
+* [Getting Started](#getting-started)
+    * [Making Changes](#making-changes)
+* [Getting in Touch](#getting-in-touch)
+    * [Got a question or problem?](#got-a-question-or-problem?)
+    * [Vulnerability Reporting](#vulnerability-reporting)
+
+## Code of Conduct
+
+By participating and contributing to this project, you are expected to uphold our [Code of Conduct](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md).
+
+## Getting Started
+
+### Making Changes
+
+To contribute to a repository, the first step is to open a support ticket
+
+[Opening a ticket] (https://auth0.com/docs/troubleshoot/customer-support/open-and-manage-support-tickets).
+
+## Getting in touch
+
+### Have a question or problem?
+
+Please do not open issues for general support or usage questions. Instead, join us over in the Auth0 community at [community.auth0.com](https://community.auth0.com) and post your question there in the correct category with a descriptive tag.
+
+### Vulnerability Reporting
+
+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.
+
+# More Information about this service is located in README.md at the root of this repository

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+ 
+Copyright (c) 2015 Auth0, Inc. <support@auth0.com> (http://auth0.com)
+ 
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+ 
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+ 
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -23,3 +23,65 @@ Password policies presets used by Auth0. Extracted from [password-sheriff](https
 * minimum characters: 10 
 * contains at least one character in three different groups out of: lowerCase, upperCase, numbers, specialCharacters
 * may not contain any character repeated more than twice
+
+## Helpers
+
+### createRulesFromOptions
+Converts an Auth0 `connection.options.password_options.complexity` object into a `password-sheriff` compatible rules object, and applies default values.
+
+Usage:
+```js
+const { PasswordPolicy } = require('password-sheriff');
+const { createRulesFromOptions } = require('auth0-password-policies');
+
+const passwordOptions = {
+  character_types: ["uppercase","lowercase","number","special"],
+  "require_3of4_character_types": true,
+  identical_characters: "disallow"
+};
+
+const rules = createRulesFromOptions(passwordOptions);
+const customPolicy = new PasswordPolicy(rules);
+console.log(customPolicy.toString());
+/**
+* Output is:
+* * At least 15 characters in length
+* * 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. !@#$%^&*)
+* * No more than 2 identical characters in a row (e.g., "aaa" not allowed)
+*/
+```
+
+## Publishing
+
+This package is automatically published to npm when:
+
+1. **Tests pass**: All tests must pass across Node.js versions 16, 18, and 20
+2. **Version tag is pushed**: Create and push a git tag following semantic versioning
+
+### Publishing Steps
+
+1. Update the version in `package.json`:
+   ```bash
+   npm version patch    # For bug fixes (1.0.0 -> 1.0.1)
+   npm version minor    # For new features (1.0.0 -> 1.1.0)  
+   npm version major    # For breaking changes (1.0.0 -> 2.0.0)
+   npm version prerelease --preid=beta  # For beta releases (1.0.0 -> 1.0.1-beta.0)
+   ```
+
+2. Push the tag to trigger publishing:
+   ```bash
+   git push origin master --tags
+   ```
+
+The workflow will:
+- Run tests across multiple Node.js versions
+- Only publish if all tests pass (using `needs: test`)
+- Publish with the appropriate npm tag (`latest` for stable, `beta` for pre-releases)
+- Use provenance for enhanced security
+
+### Tag Format
+Tags must follow the format: `v1.2.3` or `v1.2.3-beta` or `v1.2.3-beta.1`

package/index.js

@@ -1,38 +1,147 @@
-var charsets = require('password-sheriff').charsets;
+const charsets = require("password-sheriff").charsets;
 
-var upperCase = charsets.upperCase;
-var lowerCase = charsets.lowerCase;
-var numbers = charsets.numbers;
-var specialCharacters = charsets.specialCharacters;
+const upperCase = charsets.upperCase;
+const lowerCase = charsets.lowerCase;
+const numbers = charsets.numbers;
+const specialCharacters = charsets.specialCharacters;
 
-var policies = {
+const policies = {
   none: {
-    length: { minLength: 1 }
+    length: { minLength: 1 },
   },
   low: {
-    length: { minLength: 6 }
+    length: { minLength: 6 },
   },
   fair: {
     length: { minLength: 8 },
     contains: {
-      expressions: [lowerCase, upperCase, numbers]
-    }
+      expressions: [lowerCase, upperCase, numbers],
+    },
   },
   good: {
     length: { minLength: 8 },
     containsAtLeast: {
       atLeast: 3,
-      expressions: [lowerCase, upperCase, numbers, specialCharacters]
-    }
+      expressions: [lowerCase, upperCase, numbers, specialCharacters],
+    },
   },
   excellent: {
     length: { minLength: 10 },
     containsAtLeast: {
       atLeast: 3,
-      expressions: [lowerCase, upperCase, numbers, specialCharacters]
+      expressions: [lowerCase, upperCase, numbers, specialCharacters],
     },
-    identicalChars: { max: 2 }
-  }
+    identicalChars: { max: 2 },
+  },
+};
+
+const CHARACTER_TYPES = {
+  LOWERCASE: "lowercase",
+  UPPERCASE: "uppercase",
+  NUMBER: "number",
+  SPECIAL: "special",
 };
 
+/**
+ * @typedef {Object} PasswordOptions
+ * @property {number} [min_length=15] - Minimum password length (1-72)
+ * @property {Array<'uppercase'|'lowercase'|'number'|'special'>} [character_types=[]] - Required character types
+ * @property {boolean} [require_3of4_character_types=false] - Whether to require 3 out of 4 character types (requires all 4 types to be specified)
+ * @property {'allow'|'disallow'} [identical_characters='disallow'] - Whether to allow >2 identical consecutive characters
+ */
+
+/**
+ * Default values for password options
+ * @constant
+ * @type {PasswordOptions}
+ */
+const DEFAULT_PASSWORD_OPTIONS = {
+  min_length: 15,
+  character_types: [],
+  require_3of4_character_types: false,
+  identical_characters: "disallow",
+};
+
+/**
+ * Creates a PasswordPolicy rules configuration from an Auth0
+ * `connection.options.password_options.complexity` object.
+ *
+ * @param {PasswordOptions} options - Auth0 password_options.complexity object
+ * @returns {Object} password-sheriff rules configuration object that can be passed to PasswordPolicy constructor
+ */
+function createRulesFromOptions(options = {}) {
+  const rules = {};
+
+  // Apply defaults
+  const {
+    min_length: minLength,
+    character_types: requiredTypes,
+    require_3of4_character_types: require3of4,
+    identical_characters: identicalChars,
+  } = { ...DEFAULT_PASSWORD_OPTIONS, ...options };
+
+  // Validate min_length is within acceptable range
+  if (minLength < 1 || minLength > 72) {
+    throw new Error("min_length must be between 1 and 72");
+  }
+
+  // Handle min_length
+  rules.length = { minLength: minLength };
+
+  // Validate require_3of4_character_types prerequisite
+  if (require3of4) {
+    const hasAllFourTypes = Object.values(CHARACTER_TYPES).every(function (
+      type
+    ) {
+      return requiredTypes.includes(type);
+    });
+
+    if (!hasAllFourTypes) {
+      throw new Error(
+        `require_3of4_character_types can only be used when all four character types (${Object.values(
+          CHARACTER_TYPES
+        ).join(", ")}) are selected`
+      );
+    }
+  }
+
+  if (requiredTypes.length > 0 || require3of4) {
+    const expressions = [];
+
+    if (require3of4) {
+      // Use containsAtLeast with 3 out of 4
+      rules.containsAtLeast = {
+        atLeast: 3,
+        expressions: [lowerCase, upperCase, numbers, specialCharacters],
+      };
+    } else {
+      // Map character types to expressions
+      if (requiredTypes.includes(CHARACTER_TYPES.LOWERCASE)) {
+        expressions.push(lowerCase);
+      }
+      if (requiredTypes.includes(CHARACTER_TYPES.UPPERCASE)) {
+        expressions.push(upperCase);
+      }
+      if (requiredTypes.includes(CHARACTER_TYPES.NUMBER)) {
+        expressions.push(numbers);
+      }
+      if (requiredTypes.includes(CHARACTER_TYPES.SPECIAL)) {
+        expressions.push(specialCharacters);
+      }
+
+      rules.contains = {
+        expressions: expressions,
+      };
+    }
+  }
+
+  if (identicalChars === "disallow") {
+    rules.identicalChars = { max: 2 };
+  }
+
+  return rules;
+}
+
 module.exports = policies;
+
+module.exports.createRulesFromOptions = createRulesFromOptions;

package/jest.config.json

@@ -0,0 +1,5 @@
+{
+  "testEnvironment": "node",
+  "testMatch": ["<rootDir>/test/**/*.js"],
+  "verbose": true
+}

package/opslevel.yml

@@ -0,0 +1,6 @@
+---
+version: 1
+repository:
+  owner: iam_user_management
+  tier:
+  tags:

package/package.json

@@ -1,10 +1,16 @@
 {
   "name": "auth0-password-policies",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "main": "index.js",
   "repository": "git@github.com:auth0/auth0-password-policies.git",
   "author": "Shaun Starsprung <shaun.starsprung@auth0.com>",
-  "license": "MIT",
+  "license": "UNLICENSED",
+  "scripts": {
+    "test": "jest"
+  },
+  "devDependencies": {
+    "jest": "^29.0.0"
+  },
   "dependencies": {
     "password-sheriff": "^1.1.0"
   }

package/test/test.js

@@ -0,0 +1,173 @@
+const policies = require("..");
+const { createRulesFromOptions } = policies;
+
+describe("password policies", function () {
+  describe("main export", function () {
+    it("should export all props", function () {
+      expect(Object.keys(policies)).toEqual(
+        expect.arrayContaining([
+          "none",
+          "low",
+          "fair",
+          "good",
+          "excellent",
+          "createRulesFromOptions",
+        ])
+      );
+    });
+  });
+
+  describe("createRulesFromOptions helper", function () {
+    describe("min_length", function () {
+      it("should test min_length from 1 to 72", function () {
+        const auth0Config1 = {
+          min_length: 1,
+          identical_characters: "allow",
+        };
+        const rules = createRulesFromOptions(auth0Config1);
+        expect(rules).toEqual({
+          length: {
+            minLength: 1,
+          },
+        });
+
+        const auth0Config72 = {
+          min_length: 72,
+          identical_characters: "allow",
+        };
+        const rules72 = createRulesFromOptions(auth0Config72);
+        expect(rules72).toEqual({
+          length: {
+            minLength: 72,
+          },
+        });
+      });
+
+      it("should throw an error when min_length > 72", function () {
+        expect(function () {
+          const auth0Config = {
+            min_length: 73,
+          };
+          createRulesFromOptions(auth0Config);
+        }).toThrow("min_length must be between 1 and 72");
+      });
+    });
+
+    describe("character_types", function () {
+      it("should enforce required character types", function () {
+        const auth0Config = {
+          character_types: ["lowercase", "uppercase", "number", "special"],
+          identical_characters: "allow",
+          min_length: 4,
+        };
+        const rules = createRulesFromOptions(auth0Config);
+        expect(rules).toHaveProperty("length");
+        expect(rules.length).toEqual({ minLength: 4 });
+        expect(rules).toHaveProperty("contains");
+        expect(rules.contains).toHaveProperty("expressions");
+        expect(rules.contains.expressions).toHaveLength(4);
+        // Verify each expression has test and explain functions
+        rules.contains.expressions.forEach(function (expr) {
+          expect(expr).toHaveProperty("test");
+          expect(expr).toHaveProperty("explain");
+          expect(typeof expr.test).toBe("function");
+          expect(typeof expr.explain).toBe("function");
+        });
+      });
+    });
+
+    describe("require_3of4_character_types", function () {
+      it("should enforce 3 out of 4 character types when all 4 types are specified", function () {
+        const auth0Config = {
+          character_types: ["lowercase", "uppercase", "number", "special"],
+          require_3of4_character_types: true,
+          identical_characters: "allow",
+          min_length: 3,
+        };
+        const rules = createRulesFromOptions(auth0Config);
+        expect(rules).toHaveProperty("length");
+        expect(rules.length).toEqual({ minLength: 3 });
+        expect(rules).toHaveProperty("containsAtLeast");
+        expect(rules.containsAtLeast).toHaveProperty("atLeast", 3);
+        expect(rules.containsAtLeast).toHaveProperty("expressions");
+        expect(rules.containsAtLeast.expressions).toHaveLength(4);
+        // Verify each expression has test and explain functions
+        rules.containsAtLeast.expressions.forEach(function (expr) {
+          expect(expr).toHaveProperty("test");
+          expect(expr).toHaveProperty("explain");
+          expect(typeof expr.test).toBe("function");
+          expect(typeof expr.explain).toBe("function");
+        });
+      });
+
+      it("should throw an error when require_3of4_character_types is used without all 4 character types", function () {
+        expect(function () {
+          const auth0Config = {
+            character_types: ["lowercase", "uppercase"],
+            require_3of4_character_types: true,
+          };
+          createRulesFromOptions(auth0Config);
+        }).toThrow(
+          "require_3of4_character_types can only be used when all four character types (lowercase, uppercase, number, special) are selected"
+        );
+      });
+    });
+
+    describe("identical_characters", function () {
+      it("should disallow more than 2 identical characters when specified", function () {
+        const auth0Config = {
+          identical_characters: "disallow",
+        };
+        const rules = createRulesFromOptions(auth0Config);
+        expect(rules).toEqual({
+          length: {
+            minLength: 15,
+          },
+          identicalChars: {
+            max: 2,
+          },
+        });
+      });
+
+      it("should allow more than 2 identical characters when specified", function () {
+        const auth0Config = {
+          identical_characters: "allow",
+        };
+        const rules = createRulesFromOptions(auth0Config);
+        expect(rules).toEqual({
+          length: {
+            minLength: 15,
+          },
+        });
+      });
+    });
+
+    describe("default values", function () {
+      it("should apply default values when not specified", function () {
+        const auth0Config = {};
+        const rules = createRulesFromOptions(auth0Config);
+        expect(rules).toEqual({
+          length: {
+            minLength: 15,
+          },
+          identicalChars: {
+            max: 2,
+          },
+        });
+      });
+
+      it("should allow overriding default values", function () {
+        const auth0Config = {
+          min_length: 5,
+          identical_characters: "allow",
+        };
+        const rules = createRulesFromOptions(auth0Config);
+        expect(rules).toEqual({
+          length: {
+            minLength: 5,
+          },
+        });
+      });
+    });
+  });
+});

package/yarn.lock

@@ -1,7 +0,0 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
-# yarn lockfile v1
-
-
-password-sheriff@^1.1.0:
-  version "1.1.0"
-  resolved "https://registry.yarnpkg.com/password-sheriff/-/password-sheriff-1.1.0.tgz#fdb3c3d845a0a3c92de422b2ad9346ce08a71413"