NAME

Vigil::Token - Cryptographically secure, URL-safe token generator for OTPs, sessions, and custom codes.

SYNOPSIS

EXAMPLE 1.
#!/user/bin/perl
    
use Vigil::Token;
my $token = Vigil::Token->new;
    
my $session_token = $token->custom_token(256);
    
my $short_token = $token->custom_token(12);
    
my $some_token = $token->(16);    #An alias for $token->custom_token(16);
    
my $digits_be_6_for_otp = $token->otp(6);

DESCRIPTION

Vigil::Token is a sleek, high-octane token generator that effortlessly handles both human-friendly codes and machine-to-machine secrets. Need a short, 6-digit OTP that users can type without mistaking a 0 for an O? Done. Looking for a massive, 256-character session token to lock down API calls or web sessions? Done. Every token is backed by cryptographically strong randomness using Bytes::Random::Secure, ensuring each byte of entropy is truly unpredictable. All strings are automatically URL-safe via Base64URL encoding, so they slide seamlessly into cookies, query strings, or HTML forms without worrying about escaping. With its flexible custom_token() function, Vigil::Token balances readability and security perfectly: short codes are human-friendly, long codes maximize entropy, and all tokens are guaranteed to be the exact length you request. Lightweight, reliable, and unrelentingly secure, Vigil::Token is the ultimate Swiss Army knife for modern web authentication and cryptographic token needs.

OBJECT METHODS

• my $one_time_password = $obj->otp( LENGTH )

  Returns a string of digits only. Will return up to 12 digits as specified by LENGTH.

• $obj->custom_token( LENGTH );

  Returns a string that is automatically URL-safe via Base64URL encoding. The number of characters in the string is determined by LENGTH.

Local Installation

If your host does not allow you to install from CPAN, then you can install this module locally two ways:

• Same Directory

  In the same directory as your script, create a subdirectory called "Vigil". Then add these two lines, in this order, to your script:

        use lib '.';           # Add current directory to @INC
        use Vigil::Token;      # Now Perl can find the module in the same dir
        
        #Then call it as normal:
        my $token = Vigil::Token->new;
  

• In a different directory

  First, create a subdirectory called "Vigil" then add it to @INC array through a BEGIN{} block in your script:

        #!/usr/bin/perl
        BEGIN {
                push(@INC, '/path/on/server/to/Vigil');
        }
        
        use Vigil::Token;
        
        #Then call it as normal:
        my $token = Vigil::Token->new;
  

AUTHOR

Jim Melanson (jmelanson1965@gmail.com).

Created: July, 2017.

Last Update: August 2025.

License: Use it as you will, and don't pretend you wrote it - be a mensch.

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.