encoded_token 1.0.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94f6aff78bcde0cd3cd00402ebf39c4ae1967529448e3d3f821329ad2e469e52
-  data.tar.gz: 34a07e6096e29a16c13adc2e59add378174d8b43796959d76b0e46e38028ebd8
+  metadata.gz: 50fba0475e4de9c89299be7eec8a694dd602561b001d42c77d36cb16d654cfd6
+  data.tar.gz: 443f35ddbdc837ae6dd851ae426342fb4a3c305f51cda9fdb2dfa0dc1652d25b
 SHA512:
-  metadata.gz: bffcc7452c6b6edbb1c4e82da354a925c5804583579e537344260c7b1d0f8145a9fd171adc676982a0dc808cf52f3195cb8b6036c9847b2893438d48a864d462
-  data.tar.gz: 054e5e5e05415062b40404a5ef0bd231d393840c30169375f6de1257b652b242315b234a14715dad933c3bca584a8ddfeecba070461c28539116e5b239427e2a
+  metadata.gz: 1dfad2067b675873e7c2c786180e9641c7172202a5ff3d282b7cb111756e5e2eea1e59a43d94cb29c1b701e1260ddd773c43d82e0fc0601e9128753707b64b16
+  data.tar.gz: ae1f469da08ca88d1d1490877a735d12b1e12ac2e754993ae069ff730afa778cd6abd2639651008ca038be5f5171cfe23e706071a4c751ad11f03455090ddaa4

data/lib/encoded_token/cipher.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+module EncodedToken
+  ##
+  # EncodedToken::Cipher
+  #
+  #   This class represents a cipher used by EncodedToken::Encryptor
+  #   for encryption.
+  #
+  class Cipher
+
+    # ======================================================================
+    # = Macros
+    # ======================================================================
+
+    include EncodedToken::ErrorMessages
+
+    # ======================================================================
+    # = Constants
+    # ======================================================================
+
+    CIPHER_COUNT     = 16
+    CIPHER_CHARS     = (('0'..'9').to_a + ('a'..'z').to_a + ('A'..'Z').to_a).freeze
+    CIPHER_TEXT      = CIPHER_CHARS.join.freeze
+    CIPHER_INDEX_MAP = CIPHER_TEXT.each_char.with_index.to_h.freeze
+    HEX_CHARS        = (('a'..'f').to_a + ('A'..'F').to_a).freeze
+    HEX_NUMS         = ('0'..'9').to_a.freeze
+    SPECIAL_CHARS    = ['-'].freeze
+    HEX_TEXT         = (HEX_NUMS + HEX_CHARS + SPECIAL_CHARS).join.freeze
+    HEX_INDEX_MAP    = HEX_TEXT.each_char.with_index.to_h.freeze
+    MAX_CIPHER_COUNT = 60
+
+    # ======================================================================
+    # = Instance Methods
+    # ======================================================================
+
+    ##
+    # Initializes a new Cipher instance.
+    #
+    # @param [Integer] seed
+    #   the seed for randomization.
+    # @param [Date, Time, nil] expiry_date
+    #   the date when this cipher expires.
+    # @param [Integer] cipher_count
+    #   the number of keys to generate.
+    #
+    def initialize(seed, expiry_date = nil, cipher_count = EncodedToken.configuration.cipher_count)
+      @seed         = seed
+      @expiry_date  = expiry_date
+      @cipher_count = cipher_count
+
+      build_cipher!
+    end
+
+    ##
+    # Returns the seed used for this cipher.
+    #
+    # @return [Integer]
+    #
+    def seed
+      @seed
+    end
+
+    ##
+    # Returns a duplicate of the root key.
+    #
+    # @return [String]
+    #
+    def root_key
+      @root_key.dup
+    end
+
+    ##
+    # Sets the root key and resets the rotation.
+    #
+    # @param [String] new_key
+    #   the new root key.
+    #
+    # @return [String]
+    #   the new root key.
+    #
+    # @raise [ArgumentError]
+    #   if the key is invalid.
+    #
+    def root_key=(new_key)
+      fail_with(:invalid_root_key) unless valid_key?(new_key)
+      @root_key = new_key
+      reset!
+    end
+
+    ##
+    # Resets the key rotation to the root key.
+    #
+    # @return [nil]
+    #
+    def reset!
+      @rotation_key  = root_key
+      @rotation_keys = keys.dup
+
+      rotate_keys!(target_key: root_key)
+      nil
+    end
+
+    ##
+    # Rotates the current key.
+    #
+    # @param [String, nil] target_key
+    #   the key to rotate to.
+    #
+    # @return [String]
+    #   the new current rotation key.
+    #
+    # @raise [ArgumentError]
+    #   if the target key is invalid.
+    #
+    def rotate_keys!(target_key: nil)
+      if target_key
+        # noinspection RubyMismatchedArgumentType
+        unless valid_key?(target_key)
+          fail_with(:invalid_root_key)
+        end
+        rotation_keys.rotate! until rotation_keys.first == target_key
+      else
+        rotation_keys.rotate!
+      end
+
+      @rotation_key = rotation_keys.first
+    end
+
+    ##
+    # Checks if the given key is valid for this cipher.
+    #
+    # @param [String] key
+    #
+    # @return [Boolean]
+    #
+    def valid_key?(key)
+      keys.include?(key)
+    end
+
+    ##
+    # Returns the cipher text for the current rotation key.
+    #
+    # @return [String]
+    #
+    def text
+      key_texts[@rotation_key]
+    end
+
+    ##
+    # Returns the index map for the current rotation key.
+    #
+    # @return [Hash<String, Integer>]
+    #
+    def text_map
+      key_maps[@rotation_key]
+    end
+
+    ##
+    # Returns the padding size for the root key.
+    #
+    # @return [Integer]
+    #
+    def padding
+      @key_paddings[@root_key]
+    end
+
+    ##
+    # Returns the hex text used for encryption mapping.
+    #
+    # @return [String]
+    #
+    def hex_text
+      HEX_TEXT
+    end
+
+    ##
+    # Returns the index map for the hex text.
+    #
+    # @return [Hash<String, Integer>]
+    #
+    def hex_map
+      HEX_INDEX_MAP
+    end
+
+    ##
+    # Checks if the cipher has expired.
+    #
+    # @return [Boolean]
+    #
+    def expired?
+      @expiry_date ? Time.now > @expiry_date : false
+    end
+
+    ##
+    # Returns the number of keys in the cipher.
+    #
+    # @return [Integer]
+    #
+    def cipher_count
+      @cipher_count
+    end
+
+
+    ##
+    # Returns the current rotation key.
+    #
+    # @return [String]
+    #
+    def rotation_key
+      @rotation_key
+    end
+
+    ##
+    # Returns the map of keys to their respective cipher texts.
+    #
+    # @return [Hash<String, String>]
+    #
+    def key_texts
+      @key_texts ||= {}
+    end
+
+    ##
+    # Returns the map of keys to their respective index maps.
+    #
+    # @return [Hash<String, Hash>]
+    #
+    def key_maps
+      @key_maps ||= {}
+    end
+
+    ##
+    # Returns the map of keys to their respective padding sizes.
+    #
+    # @return [Hash<String, Integer>]
+    #
+    def key_paddings
+      @key_paddings ||= {}
+    end
+
+    ##
+    # Returns the list of keys.
+    #
+    # @return [Array<String>]
+    #
+    def keys
+      @keys ||= []
+    end
+
+    ##
+    # Returns the list of keys in their current rotation order.
+    #
+    # @return [Array<String>]
+    #
+    def rotation_keys
+      @rotation_keys ||= []
+    end
+
+    # = Private Instance Methods
+    # ======================================================================
+    #
+    private
+
+    def build_cipher!
+      return if keys.any?
+
+      randomizer         = Random.new(seed)
+      @keys              = CIPHER_CHARS.sample(cipher_count, random: randomizer)
+      @root_key          = keys.sample(random: randomizer)
+      @rotation_key      = @root_key
+      @rotation_keys     = keys.dup
+
+      rotate_keys! target_key: @rotation_key
+
+      keys.each do |key|
+        key_paddings[key] = randomizer.rand(0..10)
+        key_texts[key]    = CIPHER_CHARS.sample(HEX_TEXT.size, random: randomizer).join
+        key_maps[key]     = key_texts[key].each_char.with_index.to_h
+      end
+    end
+
+  end # CipherPack
+end

data/lib/encoded_token/configuration.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+module EncodedToken
+  ##
+  # EncodedToken::Configuration
+  #
+  #   This class manages the single configuration instance for EncodedToken.
+  #
+  class Configuration
+
+    # ======================================================================
+    # = Macros
+    # ======================================================================
+
+    include EncodedToken::ErrorMessages
+    include EncodedToken::Utils
+
+    # ======================================================================
+    # = Constants
+    # ======================================================================
+
+    DEFAULT_CIPHER_COUNT   = 16
+    DEFAULT_MIN_TOKEN_SIZE = 55
+    DEFAULT_MAX_INPUT_SIZE = 1000
+
+    # ======================================================================
+    # = Class methods
+    # ======================================================================
+
+    private_class_method :new
+
+    class << self
+
+      ##
+      # Returns the singleton instance of the Configuration.
+      #
+      # @return [Configuration]
+      #
+      def instance
+        @instance ||= new
+      end
+
+      ##
+      # Checks if the configuration is locked.
+      #
+      # @return [Boolean]
+      #
+      def locked?
+        instance.locked?
+      end
+
+      ##
+      # Checks if the configuration is unlocked.
+      #
+      # @return [Boolean]
+      #
+      def unlocked?
+        instance.unlocked?
+      end
+
+      ##
+      # Locks the configuration to prevent further changes.
+      #
+      # @return [true]
+      #   the lock status
+      #
+      def lock!
+        instance.lock!
+      end
+
+      ##
+      # Unlocks the configuration.
+      #
+      # @return [false]
+      #   the lock status
+      #
+      def unlock!
+        instance.unlock!
+      end
+
+    end # class << self
+
+    # ======================================================================
+    # = Instance Methods
+    # ======================================================================
+
+    def initialize
+      @cipher_count       = DEFAULT_CIPHER_COUNT
+      @expiring_seeds     = {}
+      @locked             = false
+      @max_input_size     = DEFAULT_MAX_INPUT_SIZE
+      @min_token_size     = DEFAULT_MIN_TOKEN_SIZE
+    end
+
+    ##
+    # Checks if the configuration is locked.
+    #
+    # @return [Boolean]
+    #
+    def locked?
+      !!@locked
+    end
+
+    ##
+    # Checks if the configuration is unlocked.
+    #
+    # @return [Boolean]
+    #
+    def unlocked?
+      !locked?
+    end
+
+    ##
+    # Locks the configuration.
+    #
+    # @return [true] the lock status
+    #
+    def lock!
+      @locked = true
+    end
+
+    ##
+    # Unlocks the configuration.
+    #
+    # @return [false] the lock status
+    #
+    def unlock!
+      @locked = false
+    end
+
+    ##
+    # Adds an expiring seed to the configuration.
+    #
+    # @param [Integer, String] expiring_seed
+    #   the seed for the expiring cipher.
+    # @param [Date, Time] expiry_date
+    #   the date when the seed expires.
+    # @param [Integer] cipher_count
+    #   the number of keys for the expiring cipher.
+    #
+    # @return [Hash]
+    #   the details of the added expiring seed.
+    #
+    # @raise [ArgumentError]
+    #   if the arguments are invalid.
+    #
+    def add_expiring_seed(expiring_seed, expiry_date, cipher_count = DEFAULT_CIPHER_COUNT)
+      assert_configuration_can_change!
+
+      key     = Integer(expiring_seed).abs rescue nil
+      c_count = Integer(cipher_count).abs rescue nil
+
+      if key && valid_date?(expiry_date) && valid_cipher_count?(c_count)
+        @expiring_seeds[key] = {expires_on: expiry_date, cipher_count: c_count}
+      else
+        fail_with(:invalid_expiry_argument)
+      end
+    end
+
+    ##
+    # Returns the default cipher count.
+    #
+    # @return [Integer]
+    #
+    def cipher_count
+      @cipher_count
+    end
+
+    ##
+    # Sets the default cipher count.
+    #
+    # @param [Integer] new_count
+    #   the new cipher count.
+    #
+    # @raise [ArgumentError, RuntimeError]
+    #   if the count is invalid or configuration is locked.
+    #
+    def cipher_count=(new_count)
+      assert_configuration_can_change!
+
+      value = Integer(new_count).abs rescue nil
+      fail_with(:invalid_cipher_count) unless valid_cipher_count?(value)
+
+      @cipher_count = value
+    end
+
+    ##
+    # Returns the map of expiring seeds.
+    #
+    # @return [Hash<Integer, Hash>]
+    #
+    def expiring_seeds
+      @expiring_seeds || {}
+    end
+
+    ##
+    # Returns the maximum input size.
+    #
+    # @return [Integer]
+    #
+    def max_input_size
+      @max_input_size
+    end
+
+    ##
+    # Sets the maximum input size.
+    #
+    # @param [Integer] max_size
+    #
+    # @raise [ArgumentError, RuntimeError]
+    #   if the size is invalid or configuration is locked.
+    #
+    def max_input_size=(max_size)
+      assert_configuration_can_change!
+
+      value = Integer(max_size).abs rescue nil
+      fail_with(:invalid_max_input_size) if value.nil? || !value.positive?
+
+      @max_input_size = value
+    end
+
+    ##
+    # Returns the minimum token size.
+    #
+    # @return [Integer]
+    #
+    def min_token_size
+      @min_token_size
+    end
+
+    ##
+    # Sets the minimum token size.
+    #
+    # @param [Integer] min_size
+    #
+    # @raise [ArgumentError, RuntimeError]
+    #   if the size is invalid or configuration is locked.
+    #
+    def min_token_size=(min_size)
+      assert_configuration_can_change!
+
+      value = Integer(min_size).abs rescue nil
+      fail_with(:invalid_min_token_size) if value.nil? || !value.positive?
+
+      @min_token_size = value
+    end
+
+    ##
+    # Returns the master seed.
+    #
+    # @return [Integer]
+    #
+    def seed
+      @seed
+    end
+
+    ##
+    # Sets the master seed.
+    #
+    # @param [Integer] new_seed
+    #
+    # @raise [ArgumentError, RuntimeError]
+    #   if the seed is invalid or configuration is locked.
+    #
+    def seed=(new_seed)
+      assert_configuration_can_change!
+
+      value = Integer(new_seed).abs rescue nil
+      fail_with(:invalid_seed) if value.nil?
+
+      @seed = value
+    end
+
+    # = Private Instance Methods
+    # ======================================================================
+    #
+    private
+
+    def assert_configuration_can_change!
+      fail_with(:no_config_change_allowed) if locked?
+    end
+
+    def valid_cipher_count?(count)
+      return true if count.is_a?(Integer) && count >= 8 && count <= Cipher::MAX_CIPHER_COUNT
+      fail_with(:invalid_expiry_argument)
+    end
+
+  end # class configuration
+end

data/lib/encoded_token/encoder/legacy_decoder.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module EncodedToken
+  module Encoder
+    ##
+    # EncodedToken::Encode::LegacyDecoder
+    #
+    #   This module represents a decoder used by EncodedToken::Encryptor
+    #   to decode legacy tokens.
+    #
+    module LegacyDecoder
+
+      # ======================================================================
+      # = Macros
+      # ======================================================================
+
+      extend EncodedToken::Utils
+      extend EncodedToken::ErrorMessages
+
+      # ======================================================================
+      # = Singleton Methods
+      # ======================================================================
+
+      class << self
+
+        ##
+        # Decodes the given legacy 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_characters) unless valid_token_text?(token)
+        end
+
+        # rubocop:disable Metrics/MethodLength
+        #
+        def parse_token(original_token)
+          Encoder.decoding_ciphers.each do |cipher|
+            begin
+              token     = original_token.dup
+              key       = token.slice!(0)
+              encryptor = EncodedToken::Encryptor.new(cipher, key) rescue next
+
+              # get the id size * padding
+              id_size   = encryptor.decrypt(token.slice!(0, 2)).to_i(16)
+              padding   = encryptor.padding
+
+              # remove the padding, get and decrypt the id
+              token.slice!(0, padding)
+              enc_id    = token.slice!(0, id_size)
+              id        = encryptor.decrypt(enc_id)
+
+              # next cipher if it's  a UUID or numeric ID
+              return id if valid_integer?(id) || valid_uuid_format?(id)
+
+            rescue
+              next
+            end
+          end
+
+          nil
+        end
+        # rubocop:enable Metrics/MethodLength
+
+      end # class << self
+    end # module LegacyDecoder
+  end # module encoder
+end # module