encoded_token 1.0.2 → 2.0.0

data/lib/encoded_token/encryptor.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module EncodedToken
+  ##
+  # EncodedToken::Encryptor
+  #
+  #   This class is responsible for encryption and decryption.
+  #
+  class Encryptor
+
+    # ======================================================================
+    # = Macros
+    # ======================================================================
+
+    include EncodedToken::ErrorMessages
+
+    # ======================================================================
+    # = Instance Methods
+    # ======================================================================
+
+    ##
+    # Validates if the given key is part of the cipher's key list.
+    #
+    # @param [String] key
+    #   the key to validate.
+    #
+    # @return [Boolean]
+    #   true if the key is valid, false otherwise.
+    #
+    def valid_key?(key)
+      @cipher.valid_key?(key)
+    end
+
+    ##
+    # Encrypts the given original string.
+    #
+    # @param [String] original_string
+    #   the string to encrypt.
+    #
+    # @return [String]
+    #   the encrypted string.
+    #
+    def encrypt(original_string)
+      process_chars(original_string, :encrypt)
+    end
+
+    ##
+    # Decrypts the given encrypted string.
+    #
+    # @param [String] encrypted_string
+    #   the string to decrypt.
+    #
+    # @return [String]
+    #   the decrypted string.
+    #
+    def decrypt(encrypted_string)
+      process_chars(encrypted_string, :decrypt)
+    end
+
+    ##
+    # Returns the random padding size for the current root key.
+    #
+    # @return [Integer]
+    #   the padding size.
+    #
+    def padding
+      @cipher.padding
+    end
+
+    ##
+    # Returns the current root key.
+    #
+    # @return [String]
+    #   the root key.
+    #
+    def key
+      @root_key
+    end
+
+    ##
+    # Returns the cipher instance.
+    #
+    # @return [Cipher]
+    #   the cipher instance.
+    #
+    def cipher
+      @cipher
+    end
+
+    # ======================================================================
+    # = Private Instance Methods
+    # ======================================================================
+    #
+    private
+
+    def initialize(cipher, root_key = nil)
+      @cipher = cipher
+
+      if root_key
+        fail_with(:invalid_root_key) unless @cipher.valid_key?(root_key)
+        @cipher.root_key = root_key
+      end
+
+      @root_key = @cipher.root_key
+    end
+
+    def process_chars(input_string, action)
+      cipher.reset!
+      result = String.new
+
+      input_string.each_char do |char|
+        cipher.rotate_keys!
+        result << (action == :decrypt ? decrypt_char(char) : encrypt_char(char))
+      end
+      result
+    end
+
+
+    def encrypt_char(char)
+      position = cipher.hex_map[char]
+      fail_with(:invalid_encryption_char) unless position
+      cipher.text[position]
+    end
+
+    def decrypt_char(char)
+      position = cipher.text_map[char]
+      unless position
+        fail_with(:invalid_decryption_char)
+      end
+      cipher.hex_text[position]
+    end
+
+  end
+end

data/lib/encoded_token/error_messages.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module EncodedToken
+  ##
+  # EncodedToken::ErrorMessages
+  #
+  #   This module contains all error handling and reporting functions.
+  #
+  module ErrorMessages
+
+    # ======================================================================
+    # = Constants
+    # ======================================================================
+
+    CONFIG_ERRORS = {
+      invalid_cipher_count:     { error_klass: ArgumentError,
+                                  message:     "cypher count must be an integer between 8 and 60." },
+      invalid_expiry_argument:  { error_klass: ArgumentError,
+                                  message:     'expiry seed must include an Integer seed, a Date or Time it expires & an Integer number of ciphers between 8 & 60 (default: 16).' },
+      invalid_max_input_size:   { error_klass: ArgumentError,
+                                  message:     'maximum input size must be an integer greater than 0.' },
+      invalid_min_token_size:   { error_klass: ArgumentError,
+                                  message:     'minimum token size must be an integer greater than 0.' },
+      invalid_seed:             { error_klass: ArgumentError,
+                                  message:     "seed must be an Integer, preferably with at least 5 digits. E.g. '12345'" },
+      no_config_change_allowed: { error_klass: RuntimeError,
+                                  message:     'configuration may not be changed once tokens have been encoded or decoded.' },
+    }.freeze
+
+    ENCRYPTOR_ERRORS = {
+      invalid_encryption_char:  { error_klass: ArgumentError,
+                                  message:     'invalid encryption character, must be hexadecimal.' },
+      invalid_decryption_char:  { error_klass: ArgumentError,
+                                  message:     'invalid decryption character.' },
+      invalid_root_key:         { error_klass: ArgumentError,
+                                  message:     'new cipher key is not included within the cipher key_list.' },
+    }.freeze
+
+    ENCODER_ERRORS = {
+      invalid_token_characters: { error_klass: ArgumentError,
+                                  message:     'invalid token characters.' },
+      invalid_utf8_input:       { error_klass: ArgumentError,
+                                  message:     'input must be an Integer, a String integer or a valid UTF-8 String.' },
+      invalid_token:            { error_klass: ArgumentError,
+                                  message:     'invalid token submitted.' },
+      non_string_token:         { error_klass: ArgumentError,
+                                  message:     'token must be a String.' },
+    }.freeze
+
+
+    CIPHER_ERRORS = {
+      invalid_cipher_seed:      { error_klass: ArgumentError,
+                                  message:     'cipher seed must be a positive Integer.' },
+      unknown_cipher_seed:      { error_klass: ArgumentError,
+                                  message:     'cipher seed not registered.' },
+    }.freeze
+
+
+    V1_ENCODER_ERRORS = {
+      invalid_id:               { error_klass: ArgumentError,
+                                  message:     'ID must be an Integer, a String integer or a String UUID.' },
+    }.freeze
+
+    ENCODED_TOKEN_ERRORS = {
+      invalid_encoder:          { error_klass: ArgumentError,
+                                  message:     'encoder should be blank, nil or :v1.' },
+      seed_not_set:             { error_klass: RuntimeError,
+                                  message:     "... looks like you haven't set a seed yet." }
+    }.freeze
+
+    ERROR_MESSAGES = {}.merge(CONFIG_ERRORS)
+                        .merge(ENCRYPTOR_ERRORS)
+                        .merge(ENCODER_ERRORS)
+                        .merge(CIPHER_ERRORS)
+                        .merge(V1_ENCODER_ERRORS)
+                        .merge(ENCODED_TOKEN_ERRORS).freeze
+
+    # ======================================================================
+    # = Private Instance Methods
+    # ======================================================================
+    #
+    private
+
+    ##
+    # Raises an exception corresponding to the given error key.
+    #
+    # @param [Symbol] error_key
+    #   the key for the error message and class.
+    #
+    # @raise [ArgumentError, RuntimeError]
+    #
+    def fail_with(error_key)
+      error_klass = ERROR_MESSAGES[error_key][:error_klass]
+      message     = ERROR_MESSAGES[error_key][:message]
+      error       = error_klass.new("\n\nERROR :=> EncodedToken: #{message}\n\n")
+                               .tap { |e| e.set_backtrace(['EncodedToken']) unless ENV['ENCODEDTOKEN_DEBUG'] }
+      fail error
+    end
+
+  end
+end

data/lib/encoded_token/utils.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module EncodedToken
+  ##
+  # EncodedToken::Utils
+  #
+  #   This module contains look-up and validation functions.
+  #
+  module Utils
+
+    # ======================================================================
+    # = Private Instance Methods
+    # ======================================================================
+    #
+    private
+
+    ##
+    # Generates a random alphanumeric string of the given size.
+    #
+    # @param [Integer] size
+    #
+    # @return [String]
+    #
+    def random_characters(size)
+      SecureRandom.alphanumeric(size)
+    end
+
+    ##
+    # Generates a random hex string of the given size.
+    #
+    # @param [Integer] size
+    #
+    # @return [String]
+    #
+    def random_hex(size)
+      EncodedToken::Cipher::HEX_CHARS.sample(size).join
+    end
+
+    ##
+    # Validates if the given object is a valid date/time.
+    #
+    # @param [Object] date
+    #
+    # @return [Boolean]
+    #
+    def valid_date?(date)
+      return true if date.is_a?(Date)
+      return true if date.is_a?(Time)
+      return true if date.is_a?(DateTime)
+
+      false
+    end
+
+    ##
+    # Validates if the given input can be converted to an Integer.
+    #
+    # @param [Object] input
+    #
+    # @return [Boolean]
+    #
+    def valid_integer?(input)
+      !!Integer(input)
+    rescue
+      false
+    end
+
+    ##
+    # Validates if the given ID matches the UUID format.
+    #
+    # @param [String] id
+    #
+    # @return [Boolean]
+    #
+    def valid_uuid_format?(id)
+      uuid_regex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
+      uuid_regex.match?(id.downcase)
+    rescue
+      false
+    end
+
+    ##
+    # Validates if the given value contains only valid hex characters.
+    #
+    # @param [String] val
+    #
+    # @return [Boolean]
+    #
+    def valid_hex_text?(val)
+      (val.chars - __hex_text.chars).empty?
+    end
+
+    ##
+    # Validates if the given value contains only valid cipher characters.
+    #
+    # @param [String] val
+    #
+    # @return [Boolean]
+    #
+    def valid_token_text?(val)
+      (val.chars - __cipher_text.chars).empty?
+    end
+
+    def __crc8_checksum(hex_string)
+      data = [hex_string].pack('H*').bytes
+      crc  = 0
+      data.each do |byte|
+        crc ^= byte
+        8.times { crc = (crc & 0x80 != 0) ? ((crc << 1) ^ 0x07) : (crc << 1) }
+        crc &= 0xFF
+      end
+      crc
+    end
+
+    def __hex_text
+      EncodedToken::Cipher::HEX_TEXT
+    end
+
+    def __cipher_text
+      EncodedToken::Cipher::CIPHER_TEXT
+    end
+
+    def __min_token_size
+      EncodedToken::Encoder.min_token_size
+    end
+
+    def __max_input_size
+      EncodedToken::Encoder.max_input_size
+    end
+
+  end
+end

data/lib/encoded_token/version.rb

@@ -1,28 +1,26 @@
 # frozen_string_literal: true
 
-
-##
-# EncodedToken version details
-#
-class EncodedToken # :nodoc:
+module EncodedToken
 
   ##
-  # The EncodedToken gem version.
+  # Returns the gem version.
   #
-  # [returns:]
-  #   - the version of the currently loaded EncodedToken as a <tt>Gem::Version</tt>
+  # @return [Gem::Version]
   #
   def self.gem_version
     Gem::Version.new VERSION::STRING
   end
 
+  ##
+  # EncodedToken::VERSION
+  #
+  #   This module represent the current version.
+  #
+  module VERSION
 
-
-  module VERSION # :nodoc: all
-
-    MAJOR = 1
+    MAJOR = 2
     MINOR = 0
-    TINY  = 2
+    TINY  = 0
     # MICRO = ''
 
     STRING = [MAJOR, MINOR, TINY].compact.join(".")

data/lib/encoded_token.rb

@@ -1,15 +1,29 @@
 # frozen_string_literal: true
 
+require          "date"
+require          "securerandom"
+require_relative "encoded_token/error_messages.rb"
+require_relative "encoded_token/cipher.rb"
+require_relative "encoded_token/utils.rb"
+require_relative "encoded_token/configuration.rb"
+require_relative "encoded_token/encryptor.rb"
+require_relative "encoded_token/encoder"
+require_relative "encoded_token/encoder/legacy_encoder.rb"
+require_relative "encoded_token/encoder/legacy_decoder.rb"
+require_relative "encoded_token/encoder/utf8_encoder.rb"
+require_relative "encoded_token/encoder/utf8_decoder.rb"
+require_relative "encoded_token/version.rb"
+
 ##
 # = EncodedToken
 #
-# Encodes a UUID or numeric ID to produce a Secure Token,
-# then decodes the Secure Token to return the origianl ID.
+# Encodes a UTF-8 String to produce a Secure Token,
+# then decodes the Secure Token to return the original input.
 #
-# - The given ID is encoded using a substitution cipher, then padded
+# - The given input is encoded using a substitution cipher, then padded
 #   with alphanumeric characters to a random length.
 #
-# - Multiple substituion ciphers are used to improve security.
+# - Multiple substitution ciphers are used to improve security.
 #
 # *examples:*
 #
@@ -19,30 +33,114 @@
 #   EncodedToken.decode("b4ex6AEB62jlBGpVAGNou8iRmD7pnHGHafQlAHB7w0J")
 #   # => "12345"
 #
-class EncodedToken
-
+module EncodedToken
+  
+  # ======================================================================
+  # = Macros
+  # ======================================================================
+  
+  extend ErrorMessages
 
   # ======================================================================
-  #  Macros
+  # = Class Methods
   # ======================================================================
+  
+  class << self
 
-  require            "securerandom"
-  require_relative   "encoded_token/base.rb"
-  require_relative   "encoded_token/encoder.rb"
-  require_relative   "encoded_token/decoder.rb"
+    ##
+    # Returns the configuration instance.
+    #
+    # @return [Configuration]
+    #   a memoized instance of the Configuration class.
+    #
+    def configuration
+      @configuration ||= Configuration.instance
+    end
 
-  extend EncodedToken::Base
-  extend EncodedToken::Encoder
-  extend EncodedToken::Decoder
+    ##
+    # Applies the provided block to the configuration and builds the ciphers.
+    #
+    # @yield [block]
+    #   a configuration block
+    #
+    # @return [void]
+    #
+    # @example
+    #   EncodedToken.configure do |config|
+    #     config.seed = 12345
+    #   end
+    #
+    def configure
+      yield(configuration)
 
+      Encoder.build_ciphers!
+    end
 
-  # ======================================================================
-  #  Public Instance Methods
-  # ======================================================================
+    ##
+    # Encodes a given input to an encoded token.
+    #
+    # @param [Integer, String, *.to_s] input
+    #   any object that responds to '.to_s'
+    # @param [:utf8, :legacy] encoder
+    #   the encoder to use.
+    #
+    # @return [String] if successful
+    # @return [nil]    if unsuccessful
+    #
+    def encode(input, encoder = :utf8)
+      Encoder.encode(input, encoder)
+    end
+
+    ##
+    # Encodes a given input to an encoded token, raising an exception
+    # if encountered
+    #
+    # @param [Integer, String, *.to_s] input
+    #   any object that responds to '.to_s'
+    # @param [:utf8, :legacy] encoder
+    #   the encoding to use.
+    #
+    # @return [String] the encoded token
+    #
+    # @raise [ArgumentError, RuntimeError]
+    #   if the encoding fails
+    #
+    def encode!(input, encoder = :utf8)
+      Encoder.encode!(input, encoder)
+    end
 
-  # This is an abstract class, so ensure no instantiation
-  def initialize # :nodoc:
-    raise NotImplementedError.new("SecureToken is an abstract class and cannot be instantiated.")
-  end
+    
+    ##
+    # Decodes a given token to the original string
+    #
+    # @param [String] token
+    #   an encoded-token string
+    #
+    # @return [String]
+    #   the decoded value if successful
+    # @return [nil]
+    #   if unsuccessful
+    #
+    def decode(token)
+      Encoder.decode(token)
+    end
 
-end #class
+    
+    ##
+    # Decodes a given token to the original string, raising an exception
+    # if encountered
+    #
+    # @param [String] token
+    #   an encoded-token string
+    #
+    # @return [String]
+    #   the decoded value
+    #
+    # @raise [ArgumentError, RuntimeError]
+    #   if the decoding fails
+    #
+    def decode!(token)
+      Encoder.decode!(token)
+    end
+  end # class << self
+end #module

metadata

@@ -1,27 +1,33 @@
 --- !ruby/object:Gem::Specification
 name: encoded_token
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 2.0.0
 platform: ruby
 authors:
 - CodeMeister
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-10-05 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: Stop hitting the DB with every secure-token submission. Encoded Tokens
-  have the ID, or UUID, encoded within the token itself - increasing both security
-  and performance. Coded in plain Ruby, EncodedToken is framework agnostic.
+description: Replacing secure-tokens, encoded-tokens are verified BEFORE accessing
+  the database, increasing both security and performance. Coded in plain Ruby, EncodedToken
+  is framework agnostic.
 email: encoded_token@codemeister.dev
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - lib/encoded_token.rb
-- lib/encoded_token/base.rb
-- lib/encoded_token/decoder.rb
+- lib/encoded_token/cipher.rb
+- lib/encoded_token/configuration.rb
 - lib/encoded_token/encoder.rb
+- lib/encoded_token/encoder/legacy_decoder.rb
+- lib/encoded_token/encoder/legacy_encoder.rb
+- lib/encoded_token/encoder/utf8_decoder.rb
+- lib/encoded_token/encoder/utf8_encoder.rb
+- lib/encoded_token/encryptor.rb
+- lib/encoded_token/error_messages.rb
+- lib/encoded_token/utils.rb
 - lib/encoded_token/version.rb
 homepage: https://github.com/Rubology/encoded_token
 licenses:
@@ -30,7 +36,6 @@ metadata:
   homepage_uri: https://github.com/Rubology/encoded_token
   source_code_uri: https://github.com/Rubology/encoded_token
   changelog_uri: https://github.com/Rubology/encoded_token/blob/master/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -38,16 +43,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.5.0
+      version: 2.6.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.22
-signing_key:
+rubygems_version: 4.0.17
 specification_version: 4
-summary: A better, more secure and efficient way to manage secure-tokens - by encoding
-  the ID, or UUID, within the token itself.
+summary: A more secure and efficient way to manage secure-tokens.
 test_files: []