Class: Tins::Token

Inherits:
String show all
Defined in:
lib/tins/token.rb

Overview

A secure token generator that creates cryptographically safe strings using customizable alphabets and random number generators.

Examples:

Basic usage

token = Tins::Token.new
# => "aB3xK9mN2pQ8rS4tU6vW7yZ1"

Custom length

token = Tins::Token.new(length: 20)
# => "xYz123AbC456DeF789GhI0jK"

Custom alphabet

token = Tins::Token.new(
  alphabet: Tins::Token::BASE16_UPPERCASE_ALPHABET,
  length: 16
)
# => "A1B2C3D4E5F6G7H8"

Custom random number generator

token = Tins::Token.new(random: Random.new(42))
# => "xYz123AbC456DeF789GhI0jK"

Constant Summary collapse

DEFAULT_ALPHABET =

Default alphabet for token generation

"0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ".freeze
BASE64_ALPHABET =

Base64 alphabet

"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/".freeze
BASE64_URL_FILENAME_SAFE_ALPHABET =

URL-safe base64 alphabet

"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_".freeze
BASE32_ALPHABET =

Base32 alphabet

"ABCDEFGHIJKLMNOPQRSTUVWXYZ234567".freeze
BASE32_EXTENDED_HEX_ALPHABET =

Extended hex base32 alphabet

"0123456789ABCDEFGHIJKLMNOPQRSTUV".freeze
BASE16_UPPERCASE_ALPHABET =

Base16 uppercase alphabet

"0123456789ABCDEF".freeze
BASE16_LOWERCASE_ALPHABET =

Base16 lowercase alphabet

"0123456789abcdef".freeze
BASE16_ALPHABET =

Base16 default alphabet (uppercase)

BASE16_UPPERCASE_ALPHABET

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(bits: 128, length: nil, alphabet: DEFAULT_ALPHABET, random: SecureRandom) ⇒ Tins::Token

Initializes a new Token instance with specified bit length, length, alphabet, and random number generator.

Examples:

Basic initialization

token = Tins::Token.new
# => "aB3xK9mN2pQ8rS4tU6vW7yZ1"

Custom parameters

token = Tins::Token.new(
  bits: 256,
  alphabet: Tins::Token::BASE32_ALPHABET
)

Parameters:

  • bits (Integer) (defaults to: 128) —

    the number of bits for the token (default: 128)

  • length (Integer) (defaults to: nil) —

    the length of the token (optional, mutually exclusive with bits)

  • alphabet (String) (defaults to: DEFAULT_ALPHABET) —

    the alphabet to use for token generation (default: DEFAULT_ALPHABET)

  • random (Object) (defaults to: SecureRandom) —

    the random number generator to use (default: SecureRandom)

Raises:

  • (ArgumentError) —

    if alphabet has fewer than 2 symbols

  • (ArgumentError) —

    if bits is not positive when length is not specified

  • (ArgumentError) —

    if length is not positive when specified



76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/tins/token.rb', line 76

def initialize(bits: 128, length: nil, alphabet: DEFAULT_ALPHABET, random: SecureRandom)
  alphabet.size > 1 or raise ArgumentError, 'need at least 2 symbols in alphabet'
  if length
    length > 0 or raise ArgumentError, 'length has to be positive'
  else
    bits > 0 or raise ArgumentError, 'bits has to be positive'
    length = (Math.log(1 << bits) / Math.log(alphabet.size)).ceil
  end
  self.bits = (Math.log(alphabet.size ** length) / Math.log(2)).floor
  token = +''
  length.times { token << alphabet[random.random_number(alphabet.size)] }
  super token
end

Instance Attribute Details

#bits ⇒ Integer

The bit length of the token.

Returns:

  • (Integer) —

    the number of bits of entropy in the token



93
94
95
 
# File 'lib/tins/token.rb', line 93

def bits
  @bits
end