NAME

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

VERSION

       version 1.0.6

SYNOPSIS

         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;

DESCRIPTION

       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.

ATTRIBUTES

   "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"".

REQUIRED METHODS

   "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" within the
       logic that your class represents. 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.

METHODS

   "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".

AUTHOR

       Gianni Ceccarelli <gianni.ceccarelli@broadbean.com>

COPYRIGHT AND LICENSE

       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.