Data::Password::zxcvbn::Match - role for match objects

"token"
       Required string: the portion of the password that this object matches. For example, if your class
       represents "sequences of digits", an instance made from the password "abc1234def" would have "token =>
       '1234'".

   "i","j"
       Required integers: the indices of the first and last character of "token" in the password. For the
       example above, we would have "i => 3, j => 6".

   "guesses"
       The estimated number of attempts that a generic password cracker would need to guess the particular
       "token". The value for this attribute is generated on demand by calling ""estimate_guesses"".

       Gianni Ceccarelli <gianni.ceccarelli@broadbean.com>

       This software is copyright (c) 2022 by BroadBean UK, a CareerBuilder Company.

       This  is  free  software;  you  can  redistribute  it and/or modify it under the same terms as the Perl 5
       programming language system itself.

perl v5.36.0                                       2023-04-04                 Data::Password::zxcvbn::Match(3pm)

       zxcvbn estimates the strength of a password by guessing which way a generic password cracker would
       produce it, and then guessing after how many tries it would produce it.

       This role provides the basic behaviour and interface for the classes that implement that guessing.

"compare"
         $match1 <=> $match2
         $match1 cmp $match2

       The comparison operators are overloaded to sort by ""i"" and ""j"", so a sorted list of matches will
       cover the password from left to right.

   "guesses_log10"
       The logarithm in base 10 of ""guesses"".

   "guesses_for_password"
         my $guesses = $match->guesses_for_password($password);

       This method will return the same value as ""guesses"", or some minimum number of guesses, whichever is
       higher.

       This is to make sure that all match have a measurable impact on the estimation of the total complexity.

   "get_feedback"
         my %feedback = %{ $match->get_feedback($is_sole_match) };

       Returns a hashref, with verbal feedback to help choose better passwords. The hash contains:

       •   "warning"

           string (or arrayref for localisation), produced by calling ""feedback_warning""

       •   "suggestions"

           arrayref of strings (or arrayrefs for localisation), produced by calling ""feedback_suggestions"".

   "TO_JSON""fields_for_json"
       Matches can be serialised to JSON. The serialisation will be a dictionary with all the fields returned by
       ""fields_for_json"". By default, it will contain "token i j guesses guesses_log10".

       Data::Password::zxcvbn::Match - role for match objects

"make"
         sub make {
           my ($class, $password) = @_;
           return [ $class->new(\%something), ... ];
         }

       This factory method should return a sorted arrayref of instances, one for each substring of the $password
       that could be generated / guessed with the logic that your class represents.

   "estimate_guesses"
         sub estimate_guesses {
           my ($self) = @_;
           return $self->some_complexity_estimate();
         }

       This method should return an integer, representing an estimate of the number of attempts that a generic
       password cracker would need to guess the particular "token" withinthelogicthatyourclassrepresents.
       For example, if your class represents "sequences of digits", you could hypothesise that the cracker would
       go in order from 1, so you'd write:

         sub estimate_guesses { return 0 + shift->token }

   "feedback_warning"
       This method should return a string (possibly empty), or an arrayref "[$string,@values]" suitable for
       localisation. The returned value should explain what's wrong, e.g. 'this is a top-10 common password'.

   "feedback_suggestions"
       This method should return a possibly-empty array of suggestions to help choose a less guessable password.
       e.g. 'Add another word or two'; again, elements can be strings or arrayrefs for localisation.

         package My::Password::Match::Something;
         use Moo;
         with 'Data::Password::zxcvbn::Match';

         has some_info => (is=>'ro');

         sub make {
           my ($class, $password) = @_;
           return [ $class->new({
             token => some_substring_of($password),
             i => position_of_first_char($token,$password),
             j => position_of_last_char($token,$password),
             some_info => whatever_needed(),
           }) ];
         }

         sub estimate_guesses {
           my ($self) = @_;
           return $self->some_complexity_estimate();
         }

         sub feedback_warning { 'this is a bad idea' }
         sub feedback_suggestions { return [ 'do something else' ] }

         1;

       version 1.1.2