encoded_token 1.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 94f6aff78bcde0cd3cd00402ebf39c4ae1967529448e3d3f821329ad2e469e52
+  data.tar.gz: 34a07e6096e29a16c13adc2e59add378174d8b43796959d76b0e46e38028ebd8
+SHA512:
+  metadata.gz: bffcc7452c6b6edbb1c4e82da354a925c5804583579e537344260c7b1d0f8145a9fd171adc676982a0dc808cf52f3195cb8b6036c9847b2893438d48a864d462
+  data.tar.gz: 054e5e5e05415062b40404a5ef0bd231d393840c30169375f6de1257b652b242315b234a14715dad933c3bca584a8ddfeecba070461c28539116e5b239427e2a

data/lib/encoded_token/base.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+##
+# EncodedToken::Base
+#
+# The core configuration settings used for encoding and decoding, along
+# with the methods for initialization and verification.
+#
+# Encoding is achived though a variation of Alberti's cipher for
+# multiple Ciphertext Alphabets.
+# (https://en.wikipedia.org/wiki/Alberti_cipher
+#
+class EncodedToken
+  module Base
+
+    # ======================================================================
+    #  Configuration
+    # ======================================================================
+
+    HEX_NUMS         = ('0'..'9').to_a
+    HEX_CHARS        = ('a'..'f').to_a + ('A'..'F').to_a
+    SPECIAL_CHARS    = ['-']
+    HEX_TEXT         = (HEX_NUMS + HEX_CHARS + SPECIAL_CHARS).join # :nodoc:
+
+    CIPHER_CHARS     = ('0'..'9').to_a + ('a'..'z').to_a + ('A'..'Z').to_a
+    CIPHER_TEXT      = CIPHER_CHARS.join # :nodoc:
+    CIPHER_COUNT     = 16 # :nodoc:
+    TARGET_SIZE      = 55 # :nodoc:
+
+    private_constant :HEX_NUMS, :HEX_CHARS, :SPECIAL_CHARS, :CIPHER_CHARS
+
+    @@seed           = nil
+    @@ciphers        = nil
+    @@keylist        = nil
+
+
+
+    # ======================================================================
+    #  Public Methods
+    # ======================================================================
+
+    ##
+    # Sets the seed to be used in generating a random encoding
+    #
+    # [returns:]
+    #    - true on success
+    #
+    # [on error:]
+    #    - raises an exception
+    #
+    def seed=(new_seed)
+      if @@seed
+        fail_with_seed_already_set
+      else
+        @@seed = parse_seed(new_seed)
+        generate_ciphers
+        return true
+      end
+    end
+
+
+
+    # ======================================================================
+    #  Class Private Methods
+    # ======================================================================
+    private
+
+
+    # parse the new seed to ensure it is an integer
+    #
+    # return the Integer seed on success, otherwise raises an error
+    #
+    def parse_seed(new_seed)
+      if valid_integer?(new_seed)
+        return new_seed.to_i.abs
+      else
+        fail_with_invalid_seed_argument
+      end
+    end
+
+
+
+    # Generate a set of ciphers
+    #
+    # returns - a Hash of ciphers with a CIPHER_CHARS character for each key
+    #
+    def generate_ciphers
+      ciphers = {}
+      random  = Random.new(__seed)
+      keys    = CIPHER_CHARS.sample(__cipher_count, random: random).sort_by(&:downcase)
+      @@keylist = keys
+
+      # for each key, add a hash of the padding chareacter count
+      # and a cipher string to be used for encryption, using a different seed each time
+      keys.each_with_index do |key, idx|
+        ciphers[key] = {
+          padding:     random.rand(0..10),
+          cipher_text: CIPHER_CHARS.sample(HEX_TEXT.size, random: random).join
+        }
+      end
+
+      @@ciphers = ciphers
+    end
+
+
+
+    # return the next cypher key after the given key, looping to the first when required
+    def rotate_cipher_key(key)
+      idx             = __keylist.index(key) + 1
+      __keylist[idx] || __keylist.first
+    end
+
+
+
+    #  Validity
+    # ======================================================================
+
+    # checks if the seed had been set
+    #   - returns true if the seed is set
+    #   - set the seed if missing and a valid ENV['ENCODED_TOKEN_SEED'] is present
+    #
+    def assert_valid_seed!
+      case
+      when !!@@seed
+        true
+
+      when !!ENV['ENCODED_TOKEN_SEED']
+        assert_valid_env!
+        self.seed = ENV['ENCODED_TOKEN_SEED'].to_i
+
+      else
+        fail RuntimeError, "Encryption seed must be set before using EncodedToken."\
+                           " Set the seed with EncodedToken.seed=(xxx)."
+      end
+    end
+
+
+
+    # check ENV['ENCODED_TOKEN_SEED'] is a string integer
+    def assert_valid_env!
+      begin
+        if valid_integer?(ENV['ENCODED_TOKEN_SEED'])
+          return true
+        else
+          fail
+        end
+      rescue
+        fail RuntimeError, "ENV['ENCODED_TOKEN_SEED'] must be a string encoded Integer."
+      end
+    end
+
+
+
+    # Return true if the given String only contains hex text
+    def valid_hex_text?(val)
+      (val.chars - __hex_text.chars).empty?
+    end
+
+
+
+    # returns true if the given id is is an integer, else false
+    #
+    # id - and Inetger or String
+    #
+    def valid_integer?(id)
+      sid = id.to_s
+      sid.to_i.to_s == sid
+    rescue
+      false
+    end
+
+
+
+    # Return true if the given String only contains cipher text text
+    def valid_token_text?(val)
+      (val.chars - __cipher_text.chars).empty?
+    end
+
+
+
+    # returns true if the given id is a UUID, else false
+    #
+    # id - String uuid
+    #
+    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
+
+
+
+    #  Configuration Attributes
+    # ======================================================================
+
+    # return the number of ciphers
+    def __cipher_count
+      CIPHER_COUNT
+    end
+
+
+
+    # return the cipher keylist
+    def __keylist
+      @@keylist
+    end
+
+
+
+    # return the constant cypher text
+    def __cipher_text
+      CIPHER_TEXT
+    end
+
+
+
+    # return the base ciphers hash
+    def __ciphers
+      @@ciphers
+    end
+
+
+
+    # return the constant hex text
+    def __hex_text
+      HEX_TEXT
+    end
+
+
+
+    # return seed
+    def __seed
+      @@seed
+    end
+
+
+
+    # return the target size
+    def __target_size
+      TARGET_SIZE
+    end
+
+
+
+    #  Error Messages
+    # ======================================================================
+
+    # error: invalid ID supplied
+    def fail_with_invalid_id_argument
+      fail_with ArgumentError,
+                ":id must be an Integer, a String integer or a String UUID."
+    end
+
+
+
+    # error: Seed is already set
+    def fail_with_seed_already_set
+      fail_with ArgumentError,
+                "EncodedToken seed has alreay been set to #{@@seed}."
+    end
+
+
+
+    # error: invalid Seed supplied
+    def fail_with_invalid_seed_argument
+      fail_with ArgumentError,
+                ":seed must be an Integer, preferably with at least 5 digits."
+    end
+
+
+
+    # default error message header
+    def fail_with(error_klass, message)
+      fail error_klass, "\n\nERROR :=> EncodedToken: #{message}\n\n"
+    end
+
+
+  end #module
+end #class

data/lib/encoded_token/decoder.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+##
+# EncodedToken::Encoder
+#
+# The methods required to decode a token.
+#
+class EncodedToken # :nodoc:
+  module Decoder
+
+    # ======================================================================
+    #  Public Methods
+    # ======================================================================
+
+    ##
+    # Decode a previously encoded token to return the original ID
+    #
+    # [args:]
+    #   - *token* [String]
+    #
+    # [returns:]
+    #   - a String with the original ID
+    #
+    # [on error:]
+    #   - an invalid String token returns +nil+
+    #   - otherwise an exception will be raised
+    #
+    # *examples:*
+    #
+    #   EncodedToken.decode!("KY3bnaRGmyy6yJS3imWr1dcWtzDYvZjpIAYyCUo5PEKPFvQgtTTed")
+    #   #=> "12345"
+    #
+    #   EncodedToken.decode!("3gDwO7r4UJYeBYDBLU94MqjZQm0SToSE29ACDNcw0xf4QusZKxQHJ")
+    #   #=> "12345"
+    #
+    #   EncodedToken.decode!("pAi1SmpKgFAchh76EoLbYLeXVQmLwmMlH2v1zDVeufioKGr0709Qw")
+    #   #=> "468a5eeb-0cda-4c99-8dba-6a96c33003e0"
+    #
+    #   EncodedToken.decode!("abcdefghijklmnopqrstuvwxyz")
+    #   #=> nil
+    #
+    #   EncodedToken.decode!(:test)
+    #   #=> Token is not a string. (RuntimeError)
+    #
+    def decode!(token)
+      assert_valid_seed!
+
+      token = sanitize_token(token)
+      id    = parse_token(token)
+
+      # is it a UUID or numeric ID
+      if valid_integer?(id) || valid_uuid_format?(id)
+        return id
+      else
+        return nil
+      end
+    end
+
+
+
+    ##
+    # Decode a previously encoded token to return the original ID
+    #
+    # [args:]
+    #   - *token* [String]
+    #
+    # [returns:]
+    #   - a String with the original ID
+    #
+    # [on error:]
+    #   - returns +nil+
+    #
+    # *examples:*
+    #
+    #   EncodedToken.decode("KY3bnaRGmyy6yJS3imWr1dcWtzDYvZjpIAYyCUo5PEKPFvQgtTTed")
+    #   #=> "12345"
+    #
+    #   EncodedToken.decode("3gDwO7r4UJYeBYDBLU94MqjZQm0SToSE29ACDNcw0xf4QusZKxQHJ")
+    #   #=> "12345"
+    #
+    #   EncodedToken.decode("pAi1SmpKgFAchh76EoLbYLeXVQmLwmMlH2v1zDVeufioKGr0709Qw")
+    #   #=> "4ef2091f-023b-4af6-9e9f-f46465f897ba"
+    #
+    #   EncodedToken.decode("abcdefghijklmnopqrstuvwxyz")
+    #   #=> nil
+    #
+    #   EncodedToken.decode(:test)
+    #   #=> nil
+    #
+    def decode(id)
+      decode!(id)
+    rescue
+      nil
+    end
+
+
+    # ======================================================================
+    #  Private Methods
+    # ======================================================================
+    #
+    private
+
+
+    # ensures the given token is valid to decode
+    #
+    # token [String] - a properly encoded String
+    #
+    # returns - a String duplicate of the given token
+    #
+    # on error: - a RuntimeError is raised
+    #
+    # NOTE: - we return a duplicate so the original is not changed later
+    #         in the process when shifting segments
+    #
+    def sanitize_token(token)
+      fail 'Token is not a string.'   unless token.is_a?(String)
+      fail 'Invalid token characters' unless valid_token_text?(token)
+      fail 'Invalid token cipher.'    unless __keylist.include?(token[0])
+      token.dup
+    end
+
+
+
+    # Parses the token to retrieve the original ID
+    #
+    # token [String] - the encoded token
+    #
+    # returns [String] - the original ID
+    #
+    def parse_token(token)
+      key      = token[0]
+      id_size  = decrypt_size(token[1,2], key)
+      padding  = __ciphers[key][:padding]
+      enc_id   = token[padding + 3, id_size]
+
+      return decrypt(enc_id, key)
+    end
+
+
+
+    # returns the Integer size of the id
+    #
+    # enc_size - the encrypted ID
+    # key      - the cipher key to use
+    #
+    def decrypt_size(enc_size, key)
+      decrypt(enc_size, key).hex
+    end
+
+
+
+    # decrypt the id using the cipher text from the given key.
+    # - rotate the cipher every character
+    #
+    # enc_id - encoded String ID
+    # key    - base cipher key to use
+    #
+    # on error - rasies an exception (invalid cipher chars, etc)
+    #
+    def decrypt(enc_id, key)
+      id      = ""
+      enc_key = key
+
+      enc_id.each_char do |char|
+        enc_key     = rotate_cipher_key(enc_key)
+        cipher_text = __ciphers[enc_key][:cipher_text]
+
+        id += __hex_text[cipher_text.index(char)]
+      end
+
+      return id
+    rescue
+      fail 'Invalid token characters'
+    end
+
+  end #module
+end #class
+

data/lib/encoded_token/encoder.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+##
+# EncodedToken::Encoder
+#
+# The methods required to encode a token with an Integer ID or String UUID.
+#
+class EncodedToken # :nodoc:
+  module Encoder
+
+    #  Public Methods
+    # ======================================================================
+
+    ##
+    # 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
+
+
+
+    # ======================================================================
+    #  Class Private 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)
+
+      # 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')
+
+      encrypt(hex_size, key)
+    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
+
+      id.to_s.each_char do |char|
+        encipher_key = rotate_cipher_key(encipher_key)
+        cipher_text  = __ciphers[encipher_key][:cipher_text]
+
+        enc_id << cipher_text[__hex_text.index(char)]
+      end
+
+      return enc_id.join
+    end
+
+
+
+    # generate a String of alphanumeric characters ot the given size
+    #
+    def random_characters(size)
+      SecureRandom.alphanumeric(size)
+    end
+
+  end #module
+end #class
+
+
+

data/lib/encoded_token/version.rb

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

data/lib/encoded_token.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+##
+# = EncodedToken
+#
+# Encodes a UUID or numeric ID to produce a Secure Token,
+# then decodes the Secure Token to return the origianl ID.
+#
+# - The given ID is encoded using a substitution cipher, then padded
+#   with alphanumeric characters to a random length.
+#
+# - Multiple substituion ciphers are used to improve security.
+#
+# *examples:*
+#
+#   EncodedToken.encode(12345)
+#   # => "b4ex6AEB62jlBGpVAGNou8iRmD7pnHGHafQlAHB7w0J"
+#
+#   EncodedToken.decode("b4ex6AEB62jlBGpVAGNou8iRmD7pnHGHafQlAHB7w0J")
+#   # => "12345"
+#
+class EncodedToken
+
+
+  # ======================================================================
+  #  Macros
+  # ======================================================================
+
+  require            "securerandom"
+  require_relative   "encoded_token/base.rb"
+  require_relative   "encoded_token/encoder.rb"
+  require_relative   "encoded_token/decoder.rb"
+
+  extend EncodedToken::Base
+  extend EncodedToken::Encoder
+  extend EncodedToken::Decoder
+
+
+  # ======================================================================
+  #  Public Instance Methods
+  # ======================================================================
+
+  # 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
+
+end #class

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: encoded_token
+version: !ruby/object:Gem::Version
+  version: 1.0.2
+platform: ruby
+authors:
+- CodeMeister
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-10-05 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.
+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/encoder.rb
+- lib/encoded_token/version.rb
+homepage: https://github.com/Rubology/encoded_token
+licenses:
+- MIT
+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
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.22
+signing_key:
+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.
+test_files: []