policy-password
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.0 • Public • Published

    PolicyPassword
    policy-password is a library to generate passwords
    from policies given constraints.

    Contributing Guidelines · Submit an Issue


    The purpose of this library is to provide a powerful password generator based on a PasswordPolicy configuration. This especially useful when using a library such as keycloak. Keycloak provides the ability to set password policies per realm which can be obtained and parsed to generate passwords with this library.

    FOSSA Status Lint and test CodeQL codecov npm version npm downloads npm dependencies

    Installation

    To install this library, run

    yarn add policy-password
    yarn install
    

    or

    npm i policy-password
    

    depending on your package manager.

    Usage

    This library provides a class and a function based approach to generate passwords and/or policies. Generally, we need to build our policy first which we can then use to generate a password from.

    generateCompliantPassword({ policy[, constraints, includeList, excludeList, samplePolicy] })

    Generate a single password given the passwordPolicy and the minPolicyConstraints from the GeneratorConfig.

    /* Policy dictates that we want a password that is at least six characters long
       with a minimum of two special characters, two digits and two uppercase
       letters.
     */
    const policy: Policy = {
      special: 2,
      digit: 2,
      upper: 2,
    };
    /* Prepare our config that holds the policy for password generation.
     */
    const config: GeneratorConfig = { policy, samplePolicy: true };
    /* Generate 35 passwords with our predefined policy atop.
     */
    const password: Password = generateCompliantPassword(config);

    new PasswordGenerator({ policy[, constraints, includeList, excludeList, samplePolicy] }).generate()

    /* Policy dictates that we want a password that is at least 12 characters long
       with a minimum of two two digits and two uppercase letters.
     */
    const policy: Policy = {
      length: 12,
      digit: 2,
      upper: 2,
    };
    /* We want to have a constraint of minimum eight lowercase characters but only
       with letters [a-m] and not so fancy special chars.
     */
    const config: GeneratorConfig = {
      policy,
      samplePolicy: true,
      includeList: {
        ...defaultIncludeList,
        special: '!?#+-_',
        lower: 'abcdefghijklm',
      },
    };
    const passwordGenerator = new PasswordGenerator(config);
    const password: Password = passwordGenerator.generate();

    Configuration options with GeneratorConfig

    No matter the method you choose to generate a password, you always have to provide a GeneratorConfig. An overview of the various configuration options is outlined in this table:

    Option name Type Description Default value Required
    policy Policy | DefinitePolicy The policy that dictates the length and character pool for your generated passwords. {} yes
    constraints Constraints Constraints consist of mandatory minimum and maximum constraints. Constraints can be used to sample a policy when the samplePolicy flag is set to true. policyNistRecommendations (see constants.ts for more information) no
    includeList IncludeList An object that maps the individual quantifiable keys (upper, lower, digit, special) onto valid characters. The include list spans the pool of characters which are used to build the generated password. defaultIncludeList (see constants.ts for more information) no
    excludeList ExcludeList An array of characters to exclude from generated passwords. Takes precedence over the given or default include list. [] no
    samplePolicy boolean A flag to control whether a policy should be sampled from given or default constraints. false no

    How to run an example

    You can run an example, e.g. the function/password.example.ts in the examples folder like so:

    yarn run example:func
    

    Development

    In case you want to develop on or contribute to this library, make sure to check out the remote HEAD and install all dependencies with your favorite package manager for NodeJs. To run this application type

    yarn start
    

    or

    npm start
    

    Testing

    To run the test suite of this library, type

    yarn test
    

    or

    npm test
    

    Code style & lint

    Please pay attention to the .editorconfig and .eslintrc.js and stick to those rules. PR's in that regard are welcome as well!

    Author

    Thomas Hesse

    License

    FOSSA Status

    Install

    npm i policy-password

    DownloadsWeekly Downloads

    10

    Version

    1.1.0

    License

    LGPL-3.0

    Unpacked Size

    20.9 kB

    Total Files

    5

    Last publish

    Collaborators

    • tahesse