/ 
Concierge-Auth-v0.3.3
/ Concierge::Auth::Generators

NAME

Concierge::Auth::Generators - Value generation utilities for Concierge::Auth

SYNOPSIS

use Concierge::Auth::Generators qw(gen_uuid gen_random_id gen_random_token);

# Direct functional usage
my $uuid = gen_uuid();                      # Scalar: v4 UUID
my ($uuid, $msg) = gen_uuid();              # List: value + message

my $id = gen_random_id();                   # 40-char hex string (20 bytes)
my $id = gen_random_id(32);                 # 64-char hex string (32 bytes)

my $token = gen_random_token(32);           # 32-char token
my $phrase = gen_word_phrase(4, 4, 7, '-'); # "Word1-Word2-Word3-Word4"

DESCRIPTION

Concierge::Auth::Generators provides utility functions for generating various types of random values and tokens. These functions are plain subroutines (not object methods) that can be used functionally or inherited by Concierge::Auth.

All generator functions return: - Scalar context: the generated value (or undef on failure) - List context: (value, message) or (undef, error_message)

FUNCTIONS

gen_uuid()

Generates a version 4 (random) UUID using Crypt::PRNG::random_bytes. No external commands are used. The result is a standard RFC 4122 v4 UUID with 122 bits of cryptographic randomness.

my $uuid = gen_uuid();  # e.g., "550e8400-e29b-41d4-a716-446655440000"

gen_random_id($byte_length)

Generates a hex-encoded random ID from cryptographic random bytes (Crypt::PRNG::random_bytes). Default is 20 bytes (40 hex characters, 160 bits). Suitable for session IDs, API keys, and other security tokens where UUID format is not required.

my $id = gen_random_id();     # 40-char hex string (20 bytes / 160 bits)
my $id = gen_random_id(32);   # 64-char hex string (32 bytes / 256 bits)

gen_random_token($length)

Generates a random alphanumeric token. Default length is 13 characters.

my $token = gen_random_token(32);  # 32-character alphanumeric string

gen_random_string($length, $charset)

Generates a random string from specified character set. If charset is omitted or empty, uses alphanumeric characters.

my $str = gen_random_string(16, 'abcdef0123456789');  # Hex string
my $str = gen_random_string(20);  # Alphanumeric string

gen_word_phrase($num_words, $min_chars, $max_chars, $separator)

Generates a passphrase from dictionary words or falls back to random "words" if dictionary unavailable.

Parameters: - $num_words: Number of words (default: 4) - $min_chars: Minimum word length (default: 4) - $max_chars: Maximum word length (default: 7) - $separator: Word separator (default: '')

my $phrase = gen_word_phrase();           # "Word1Word2Word3Word4"
my $phrase = gen_word_phrase(5, 4, 7, '-'); # "Word1-Word2-Word3-Word4-Word5"

gen_crypt_token()

Generates an 11-character token using crypt().

my $token = gen_crypt_token();  # e.g., "ZAjQ3xY2zA9b"

gen_token()

Deprecated alias for gen_random_token().

ERROR HANDLING

Generator functions do not throw fatal errors. On failure: - Scalar context returns undef - List context returns (undef, error_message)

Functions will carp (warn) and fall back to alternative methods when possible (e.g., gen_uuid falls back to random token if uuidgen unavailable).

SEE ALSO

Concierge::Auth

AUTHOR

Bruce Van Allen <bva@cruzio.com>

LICENSE

Artistic License 2.0