encoded_token 1.0.2 → 2.0.0

data/lib/encoded_token/encoder/legacy_encoder.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module EncodedToken
+  module Encoder
+    ##
+    # EncodedToken::Encode::LegacyEncoder
+    #
+    #   This module represents the encoder used by EncodedToken::Encryptor
+    #   to encode legacy tokens.
+    #
+    module LegacyEncoder
+
+      # ======================================================================
+      # = Macros
+      # ======================================================================
+
+      extend EncodedToken::Utils
+      extend EncodedToken::ErrorMessages
+
+      # ======================================================================
+      # = Singleton Methods
+      # ======================================================================
+
+      class << self
+
+        ##
+        # Encodes the given ID into a legacy token.
+        #
+        # @param [Integer, String, *.to_s] id
+        #   the ID to encode.
+        #
+        # @return [String]
+        #   the encoded legacy token.
+        #
+        # @raise [ArgumentError]
+        #   if the ID is invalid.
+        #
+        def encode(id)
+          assert_valid_id!(id)
+          generate_token(id)
+        end
+
+        # = Private Singleton Methods
+        # ======================================================================
+        #
+        private
+
+        def assert_valid_id!(id)
+          sid = id.to_s
+          fail if     sid.empty? || sid.size > 255
+          fail unless valid_hex_text?(sid)
+          fail unless valid_integer?(sid) || valid_uuid_format?(sid)
+
+          true
+        rescue StandardError
+          fail_with(:invalid_id)
+        end
+
+
+        # rubocop:disable Metrics/MethodLength
+        #
+        def generate_token(id, user_key = nil)
+          encryptor    = EncodedToken::Encryptor.new(Encoder.encoding_cipher, user_key)
+          padding_size = encryptor.padding
+          sid          = id.to_s
+          hex_sid_size = hex_id_size(sid)
+
+          token = [
+            encryptor.key,
+            encryptor.encrypt(hex_sid_size),
+            random_characters(padding_size),
+            encryptor.encrypt(sid)
+          ].join
+
+          pad_to_min_token_size(token)
+        end
+        # rubocop:enable Metrics/MethodLength
+
+
+        def hex_id_size(sid)
+          sid.size.to_s(16).rjust(2, '0')
+        end
+
+
+        def pad_to_min_token_size(token)
+          return token if token.size >= __min_token_size
+
+          padding = random_characters(__min_token_size)
+          (token + padding).slice(0, __min_token_size)
+        end
+
+      end # class << self
+
+    end # module LegacyEncoder
+  end # module encoder
+end # module

data/lib/encoded_token/encoder/utf8_decoder.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module EncodedToken
+  module Encoder
+    ##
+    # EncodedToken::Encode::Utf8Decoder
+    #
+    #   This module represents the decoder used by EncodedToken::Encryptor
+    #   to decode UTF-8 tokens.
+    #
+    module Utf8Decoder
+
+      # ======================================================================
+      # = Macros
+      # ======================================================================
+      
+      extend EncodedToken::Utils
+      extend EncodedToken::ErrorMessages
+
+      
+      # ======================================================================
+      # = Singleton Methods
+      # ======================================================================
+
+      class << self
+        
+        ##
+        # Decodes the given UTF-8 token.
+        #
+        # @param [String] token
+        #   the token to decode.
+        #
+        # @return [String, nil]
+        #   the decoded value, or nil if unsuccessful.
+        #
+        # @raise [ArgumentError]
+        #   if the token is invalid.
+        #
+        def decode(token)
+          assert_valid_token!(token)
+          parse_token(token)
+        end
+
+        
+        # ======================================================================
+        # = Private Singleton Methods
+        # ======================================================================
+        #
+        private
+
+        def assert_valid_token!(token)
+          fail_with(:non_string_token)         unless token.is_a?(String)
+          fail_with(:invalid_token)            unless token[-1] == '_'
+          fail_with(:invalid_token_characters) unless valid_token_text?(token[0..-2])
+        end
+
+        # rubocop:disable Metrics
+        #
+        def parse_token(original_token)
+          Encoder.decoding_ciphers.each do |cipher|
+            begin
+              token     = original_token[0..-2]
+              key       = token.slice!(0)
+              encryptor = EncodedToken::Encryptor.new(cipher, key) rescue next
+
+              hex_token    = encryptor.decrypt(token)
+              padding_size = encryptor.padding
+              hex_token.slice!(0, padding_size)
+
+              data_size    = hex_token.slice!(0, 3).to_i(16)
+              hex_data     = hex_token.slice!(0, data_size)
+              crc_checksum = hex_token.slice!(0, 2).to_i(16)
+
+              next unless crc_checksum == __crc8_checksum(hex_data)
+
+              [hex_data].pack("H*").force_encoding("UTF-8")
+            rescue
+              next
+            end.tap { |result| return result if result }
+          end # each cipher
+          nil
+        end
+        # rubocop:enable Metrics
+
+      end # class << self
+
+    end # module Utf8Decoder
+  end # module encoder
+end # module

data/lib/encoded_token/encoder/utf8_encoder.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module EncodedToken
+  module Encoder
+    ##
+    # EncodedToken::Encode::Utf8Encoder
+    #
+    #   This module represents a encoder used by EncodedToken::Encryptor
+    #   to encode UTF-8 tokens.
+    #
+    module Utf8Encoder
+
+      # ======================================================================
+      # = Mcros
+      # ======================================================================
+
+      extend EncodedToken::Utils
+      extend EncodedToken::ErrorMessages
+
+
+      # ======================================================================
+      # = Singleton methods
+      # ======================================================================
+
+      class << self
+
+        ##
+        # Encodes the given input into a UTF-8 token.
+        #
+        # @param [Integer, String, *.to_s] input
+        #   the input to encode.
+        #
+        # @return [String]
+        #   the encoded UTF-8 token.
+        #
+        # @raise [ArgumentError]
+        #   if the input is invalid.
+        #
+        def encode(input)
+          assert_valid_input!(input)
+          generate_token(input)
+        end
+
+
+        # = Private Singleton Methods
+        # ======================================================================
+        #
+        private
+
+        def assert_valid_input!(input)
+          utf8 = input.to_s.force_encoding("UTF-8")
+          fail if utf8.empty? || utf8.size > __max_input_size
+
+          true
+        rescue StandardError
+          fail_with(:invalid_utf8_input)
+        end
+
+        # rubocop:disable Metrics
+        #
+        def generate_token(input, user_key = nil)
+          encryptor    = EncodedToken::Encryptor.new(Encoder.encoding_cipher, user_key)
+          padding_size = encryptor.padding
+
+          token = [
+            random_hex(padding_size),
+            hex_input_size(input),
+            hex_input(input),
+            crc_checksum(input),
+            random_hex(padding_size),
+            random_hex(rand(20).to_i)
+          ].join
+
+          token = pad_to_min_token_size(token)
+
+          [encryptor.key, encryptor.encrypt(token), '_'].join
+        end
+        # rubocop:enable Metrics
+
+        def hex_input(input)
+          input.to_s.force_encoding("UTF-8").unpack1('H*')
+        end
+
+        def hex_input_size(input)
+          hex_input(input).size.to_s(16).rjust(3, '0')
+        end
+
+        def crc_checksum(input)
+          __crc8_checksum(hex_input(input)).to_s(16).rjust(2, '0')
+        end
+
+        def pad_to_min_token_size(token)
+          return token if token.size >= __min_token_size
+
+          padding = random_hex(__min_token_size)
+          (token + padding).slice(0, __min_token_size)
+        end
+
+      end # class << self
+
+    end # class Utf8Encoder
+  end # module encoder
+end # module

data/lib/encoded_token/encoder.rb

@@ -1,196 +1,183 @@
 # frozen_string_literal: true
 
-##
-# EncodedToken::Encoder
-#
-# The methods required to encode a token with an Integer ID or String UUID.
-#
-class EncodedToken # :nodoc:
+module EncodedToken
+  ##
+  # EncodedToken::Encoder
+  #
+  #   This module handles the encoding and decoding of tokens.
+  #
   module Encoder
 
-    #  Public Methods
+    # ======================================================================
+    # = Macros
     # ======================================================================
 
-    ##
-    # Generates a Secure Token from the given ID
-    #
-    # [args:]
-    #   - *id* [Integer, String] - the ID or UUID to encode
-    #   - eg. 12345, "12345", "468a5eeb-0cda-4c99-8dba-6a96c33003e0"
-    #
-    # [returns:]
-    #   - a web-safe, variable length String of alphanumeric characters
-    #
-    # [on error:]
-    #   - raises an exception based on the error
-    #
-    # *examples:*
-    #
-    #   EncodedToken.encode!(12345)
-    #   # => "KY3bnaRGmyy6yJS3imWr1dcWtzDYvZjpIAYyCUo5PEKPFvQgtTTed"
-    #
-    #   EncodedToken.encode!("12345")
-    #   # => "3gDwO7r4UJYeBYDBLU94MqjZQm0SToSE29ACDNcw0xf4QusZKxQHJ"
-    #
-    #   EncodedToken.encode!("468a5eeb-0cda-4c99-8dba-6a96c33003e0")
-    #   # =>  "pAi1SmpKgFAchh76EoLbYLeXVQmLwmMlH2v1zDVeufioKGr0709Qw"
-    #
-    #   EncodedToken.encode!(:test)
-    #   # =>  EncodedToken: :id must be an Integer, a String integer or a String UUID. (RuntimeError)
-    #
-    def encode!(id)
-      assert_valid_seed!
-      assert_valid_id!(id)
-      generate_token(id)
-    end
-
-
-
-    ##
-    # Generates a Secure Token from the given ID
-    #
-    # [args:]
-    #   - *id* [Integer, String] - the ID or UUID to encode
-    #     - eg. 12345, "12345", "468a5eeb-0cda-4c99-8dba-6a96c33003e0"
-    #
-    # [returns:]
-    #   - a web-safe, variable length String of alphanumeric characters
-    #
-    # [on error:]
-    #   - raises an ArgumentError
-    #
-    # *examples:*
-    #
-    #   EncodedToken.encode(12345)
-    #   # => "KY3bnaRGmyy6yJS3imWr1dcWtzDYvZjpIAYyCUo5PEKPFvQgtTTed"
-    #
-    #   EncodedToken.encode("12345")
-    #   # => "3gDwO7r4UJYeBYDBLU94MqjZQm0SToSE29ACDNcw0xf4QusZKxQHJ"
-    #
-    #   EncodedToken.encode("468a5eeb-0cda-4c99-8dba-6a96c33003e0")
-    #   # =>  "pAi1SmpKgFAchh76EoLbYLeXVQmLwmMlH2v1zDVeufioKGr0709Qw"
-    #
-    #   EncodedToken.encode(:test)
-    #   # =>  EncodedToken: :id must be an Integer, a String integer or a String UUID. (RuntimeError)
-    #
-    #
-    def encode(id)
-      encode!(id)
-    rescue ArgumentError
-      fail_with_invalid_id_argument
-    end
-
+    extend EncodedToken::ErrorMessages
 
 
     # ======================================================================
-    #  Class Private Methods
+    # = Singleton Methods
     # ======================================================================
-    #
-    private
-
-
-
-    # ensures the given ID is valid to encode
-    #
-    # id - an Integer, numerical String integer or UUID
-    #    - max size of 255 characters
-    #    - contain only hex charatacters + '-'
-    #
-    # returns - true if valid
-    #
-    # on error: - an ArgumentError is raised
-    #
-    def assert_valid_id!(id)
-      sid = id.to_s
-
-      fail     if sid.size < 1
-      fail     if sid.size > 255
-      fail unless valid_hex_text?(sid)
-      fail unless valid_integer?(id) || valid_uuid_format?(id)
-
-      return true
-
-    rescue
-      fail_with_invalid_id_argument
-    end
-
-
-
-    # generates the token
-    #
-    # id - Integer, String integer or String UUID
-    #
-    # returns - an alphanumeric String token
-    #
-    # Note - token comprises [key, id_size, left_padding, enc_id, right_padding]
-    #
-    def generate_token(id)
-      # stringify the id
-      sid = id.to_s
-
-      # select a random cipher key
-      token  = key = __keylist.sample
-
-      # encrypt the id size
-      token += encrypt_size(sid, key)
-
-      # generate the left padding
-      token += random_characters(__ciphers[key][:padding])
-
-      # encrypt the id
-      token += encrypt(sid, key)
 
-      # generate right padding
-      count  = (__target_size - token.size).clamp(0, __target_size)
-      token += random_characters(count)
+    class << self
 
-      # return the new token
-      return token
-    end
-
-
-
-    # return the encrypted size of the id
-    #
-    # returns a 2-character String
-    #
-    # note - we convert to hex to allow for strings up to 255 chars
-    #
-    def encrypt_size(id, key)
-      hex_size = id.size.to_s(16).rjust(2, '0')
+      ##
+      # Checks if the ciphers have been built.
+      #
+      # @return [Boolean]
+      #   true if the encoding cipher is set, false otherwise.
+      #
+      def ciphers_built?
+        !!encoding_cipher
+      end
 
-      encrypt(hex_size, key)
-    end
+      ##
+      # Returns a duplicate of the current encoding cipher.
+      #
+      # @return [Cipher]
+      #   the encoding cipher instance.
+      #
+      def encoding_cipher
+        @encoding_cipher.dup
+      end
 
+      ##
+      # Returns a list of duplicates of the current decoding ciphers.
+      #
+      # @return [Array<Cipher>]
+      #   an array of decoding cipher instances.
+      #
+      def decoding_ciphers
+        @decoding_ciphers ||= []
+        @decoding_ciphers.map{ |cipher| cipher.dup }
+      end
 
+      ##
+      # Returns the minimum token size from configuration.
+      #
+      # @return [Integer]
+      #   the minimum size for an encoded token.
+      #
+      def min_token_size
+        EncodedToken.configuration.min_token_size
+      end
 
-    # encrypt the id using the cipher text from the given key.
-    # - rotate the cipher every character to avoid sequential valuies like id: 1000
-    #
-    def encrypt(id, key)
-      enc_id       = []
-      encipher_key = key
+      ##
+      # Returns the maximum input size from configuration.
+      #
+      # @return [Integer]
+      #   the maximum size allowed for input.
+      #
+      def max_input_size
+        EncodedToken.configuration.max_input_size
+      end
 
-      id.to_s.each_char do |char|
-        encipher_key = rotate_cipher_key(encipher_key)
-        cipher_text  = __ciphers[encipher_key][:cipher_text]
+      ##
+      # 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)
+        encode!(input, encoder)
+      rescue StandardError
+        nil
+      end
 
-        enc_id << cipher_text[__hex_text.index(char)]
+      ##
+      # 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 encoder to use.
+      #
+      # @return [String] the encoded token
+      #
+      # @raise [ArgumentError, RuntimeError]
+      #   if the encoding fails or if the seed is not set.
+      #
+      def encode!(input, encoder = :utf8)
+        fail_with(:seed_not_set) unless encoding_cipher
+
+        case encoder
+        when :utf8
+          Encoder::Utf8Encoder.encode(input)
+        when :legacy
+          Encoder::LegacyEncoder.encode(input)
+        else
+          fail_with(:invalid_encoder)
+        end
       end
 
-      return enc_id.join
-    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)
+        decode!(token)
+      rescue
+        nil
+      end
 
+      ##
+      # 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, if the token is not a string, or if the seed is not set.
+      #
+      def decode!(token)
+        fail_with(:seed_not_set)     unless encoding_cipher
+        fail_with(:non_string_token) unless token.is_a?(String)
+
+        if token[-1] == '_'
+          Utf8Decoder.decode(token)
+        else
+          LegacyDecoder.decode(token)
+        end
+      end
 
+      ##
+      # Builds the encoding and decoding ciphers based on the current configuration.
+      #
+      # @return [void]
+      #
+      # @raise [RuntimeError]
+      #   if the seed is not set in the configuration.
+      #
+      def build_ciphers!
+        default_seed = EncodedToken.configuration.seed || fail_with(:seed_not_set)
+
+        @encoding_cipher  = Cipher.new(default_seed)
+        @decoding_ciphers = [@encoding_cipher]
+
+        EncodedToken.configuration.expiring_seeds.each do |exp_seed, details|
+          cipher = Cipher.new(exp_seed, details[:expires_on], details[:cipher_count])
+          @decoding_ciphers << cipher unless cipher.expired?
+        end
+      end
 
-    # generate a String of alphanumeric characters ot the given size
-    #
-    def random_characters(size)
-      SecureRandom.alphanumeric(size)
-    end
+    end # class << self
 
   end #module
-end #class
-
-
-
+end #EncodedToken