encoded_id 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87f85eb4edadbf1953f3f3343f3b4166f8bc0058593a66507f07f7dcd589d0e0
-  data.tar.gz: 03fe5a25403ad4d75279f6e7c66d5043075e1b5a42b359a117b34c83a86b269e
+  metadata.gz: b7470fbb909ebc82c703fce3e91eecce54ef2231e51f3e2146766d4990992bf6
+  data.tar.gz: 911c4dd0d467e7746484b1c06939ab911e267887a62f77713132a55b069b600e
 SHA512:
-  metadata.gz: 9f6ad0446336da43661dd07ab253c8e80e3ded3b0fb81744c9bf662ec6ddfe3937df17bb5956f538e1b3d4e059eb074e94843e01f68e37131aaf1d7aec89bd61
-  data.tar.gz: 9a6daafde92782a631571c67557665adadd5998151319a4330d3d6700ec33bf1188e37d76e7c0341721703d7de83dc72840d60b7ea9fb57655cc9fdfc3e5c967
+  metadata.gz: b21dcfcd8c816ee3b30bc50dbe4254e3ada6a619f2efa416fbca6518d43ac3143edf35d36c2b6130a25bc43bcb57fef6cf28bf13c31f1d9c1c6da327c3b9c2c9
+  data.tar.gz: 571c5b8156462dbc991a3211c2d631bcee9d03d867adff9f2f7f81436a284560824cbef3c5745df0c3cf2585a55c0a2bf3954f154a930d149b8a0d41bf7ae9b9

data/Gemfile

@@ -10,3 +10,5 @@ gem "rake", "~> 13.0"
 gem "minitest", "~> 5.0"
 
 gem "standard", "~> 1.3"
+
+gem "steep", "~> 1.2"

data/README.md

@@ -8,9 +8,9 @@ The obfuscated strings are reversible, so you can decode them back into the orig
 encoding multiple IDs at once.
 
 ```
-    reversibles = ::EncodedId::ReversibleId.new(salt: my_salt)
-    reversibles.encode([78, 45])  # "7aq6-0zqw"
-    reversibles.decode("7aq6-0zqw")  # [78, 45]
+reversibles = ::EncodedId::ReversibleId.new(salt: my_salt)
+reversibles.encode([78, 45])  # "7aq6-0zqw"
+reversibles.decode("7aq6-0zqw")  # [78, 45]
 ```
 
 Length of the ID, the alphabet used, and the number of characters per group can be configured.
@@ -19,6 +19,13 @@ The custom alphabet (at least 16 characters needed) and character group sizes is
 Easily confused characters (eg `i` and `j`, `0` and `O`, `1` and `I` etc) are mapped to counterpart characters, to help 
 common mistakes when sharing (eg customer over phone to customer service agent).
 
+Also supports UUIDs if needed
+
+```
+::EncodedId::ReversibleId.new(salt: my_salt).encode_hex("9a566b8b-8618-42ab-8db7-a5a0276401fd")
+=> "rppv-tg8a-cx8q-gu9e-zq15-jxes-4gpr-06xk-wfk8-aw"
+```
+
 ## Features
 
 Build with https://hashids.org
@@ -26,10 +33,20 @@ Build with https://hashids.org
 * Hashids are reversible, no need to persist the generated Id
 * supports slugged IDs (eg 'beef-tenderloins-prime--p5w9-z27j')
 * supports multiple IDs encoded in one `EncodedId` (eg '7aq6-0zqw' decodes to `[78, 45]`)
+* supports encoding of hex strings (eg UUIDs), including mutliple IDs encoded in one `EncodedId`
 * uses a reduced character set (Crockford alphabet) & ids split into groups of letters, ie 'human-readability'
+* profanity limitation
 
 To use with **Rails** check out the `encoded_id-rails` gem.
 
+## Note on security of encoded IDs (hashids)
+
+**Encoded IDs are not secure**. It maybe possible to reverse them via brute-force. They are meant to be used in URLs as 
+an obfuscation. The algorithm is not an encryption.
+
+Please read more on https://hashids.org/
+
+
 ## Compared to alternate Gems
 
 - https://github.com/excid3/prefixed_ids
@@ -63,10 +80,10 @@ To use with rails try the `encoded_id-rails` gem.
 
 ```ruby
     class User < ApplicationRecord
-      include EncodedId::WithUid
+      include EncodedId::WithEncodedId
     end
 
-    User.find_by_uid("p5w9-z27j")  # => #<User id: 78>
+    User.find_by_encoded_id("p5w9-z27j")  # => #<User id: 78>
 ```
 
 ## Development

data/Steepfile

@@ -0,0 +1,5 @@
+target :lib do
+  signature "sig"
+
+  check "lib"
+end

data/lib/encoded_id/reversible_id.rb

@@ -5,12 +5,12 @@ require "hashids"
 # Hashid with a reduced character set Crockford alphabet and split groups
 # See: https://www.crockford.com/wrmg/base32.html
 # Build with https://hashids.org
-# Note hashIds already has a biuld in profanity limitation algorithm
+# Note hashIds already has a built in profanity limitation algorithm
 module EncodedId
   class ReversibleId
     ALPHABET = "0123456789abcdefghjkmnpqrstuvwxyz"
 
-    def initialize(salt:, length: 8, split_at: 4, alphabet: ALPHABET)
+    def initialize(salt:, length: 8, split_at: 4, alphabet: ALPHABET, hex_digit_encoding_group_size: 4)
       unique_alphabet = alphabet.chars.uniq
       raise InvalidAlphabetError, "Alphabet must be at least 16 characters" if unique_alphabet.size < 16
 
@@ -18,32 +18,50 @@ module EncodedId
       @salt = salt
       @length = length
       @split_at = split_at
+      # Number of hex digits to encode in each group, larger values will result in shorter hashes for longer inputs.
+      # Vice versa for smaller values, ie a smaller value will result in smaller hashes for small inputs.
+      @hex_digit_encoding_group_size = hex_digit_encoding_group_size
     end
 
     # Encode the input values into a hash
-    def encode(*values)
-      uid = convert_to_string(uid_generator.encode(*values))
-      uid = humanize_length(uid) unless split_at.nil?
-      uid
+    def encode(values)
+      inputs = prepare_input(values)
+      encoded_id = encoded_id_generator.encode(inputs)
+      encoded_id = humanize_length(encoded_id) unless split_at.nil?
+      encoded_id
+    end
+
+    # Encode hex strings into a hash
+    def encode_hex(hexs)
+      encode(integer_representation(hexs))
     end
 
     # Decode the hash to original array
     def decode(str)
-      uid_generator.decode(convert_to_hash(str))
+      encoded_id_generator.decode(convert_to_hash(str))
     rescue ::Hashids::InputError => e
       raise EncodedIdFormatError, e.message
     end
 
+    # Decode hex strings from a hash
+    def decode_hex(str)
+      integers = encoded_id_generator.decode(convert_to_hash(str))
+      integers_to_hex_strings(integers)
+    end
+
     private
 
-    attr_reader :salt, :length, :human_friendly_alphabet, :split_at
+    attr_reader :salt, :length, :human_friendly_alphabet, :split_at, :hex_digit_encoding_group_size
+
+    def prepare_input(value)
+      inputs = value.is_a?(Array) ? value.map(&:to_i) : [value.to_i]
+      raise ::EncodedId::InvalidInputError, "Integer IDs to be encoded can only be positive" if inputs.any?(&:negative?)
 
-    def uid_generator
-      @uid_generator ||= ::Hashids.new(salt, length, human_friendly_alphabet)
+      inputs
     end
 
-    def convert_to_string(hash)
-      hash.is_a?(Array) ? hash.join : hash.to_s
+    def encoded_id_generator
+      @encoded_id_generator ||= ::Hashids.new(salt, length, human_friendly_alphabet)
     end
 
     def split_regex
@@ -63,5 +81,53 @@ module EncodedId
       # only use lowercase
       str.tr("o", "0").tr("l", "1").tr("i", "j")
     end
+
+    # TODO: optimize this
+    def integer_representation(hexs)
+      inputs = hexs.is_a?(Array) ? hexs.map(&:to_s) : [hexs.to_s]
+      inputs.map! do |hex_string|
+        cleaned = hex_string.gsub(/[^0-9a-f]/i, "")
+        # Convert to groups of integers. Process least significant hex digits first
+        groups = []
+        cleaned.chars.reverse.each_with_index do |char, i|
+          group_id = i / hex_digit_encoding_group_size.to_i
+          groups[group_id] ||= []
+          groups[group_id].unshift(char)
+        end
+        groups.map { |c| c.join.to_i(16) }
+      end
+      digits_to_encode = []
+      inputs.each_with_object(digits_to_encode) do |hex_digits, digits|
+        digits.concat(hex_digits)
+        digits << hex_string_separator
+      end
+      digits_to_encode.pop unless digits_to_encode.empty? # Remove the last marker
+      digits_to_encode
+    end
+
+    # Marker to separate hex strings, must be greater than largest value encoded
+    def hex_string_separator
+      @hex_string_separator ||= 2.pow(hex_digit_encoding_group_size * 4) + 1
+    end
+
+    # TODO: optimize this
+    def integers_to_hex_strings(integers)
+      hex_strings = []
+      hex_string = []
+      add_leading = false
+      # Digits are encoded in least significant digit first order, but string is most significant first, so reverse
+      integers.reverse_each do |integer|
+        if integer == hex_string_separator # Marker to separate hex strings, so start a new one
+          hex_strings << hex_string.join
+          hex_string = []
+          add_leading = false
+        else
+          hex_string << (add_leading ? "%.#{hex_digit_encoding_group_size}x" % integer : integer.to_s(16))
+          add_leading = true
+        end
+      end
+      hex_strings << hex_string.join unless hex_string.empty? # Add the last hex string
+      hex_strings.reverse # Reverse final values to get the original order (the encoding process also reverses the encoded value order)
+    end
   end
 end

data/lib/encoded_id/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module EncodedId
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/encoded_id.rb

@@ -4,7 +4,9 @@ require_relative "encoded_id/version"
 require_relative "encoded_id/reversible_id"
 
 module EncodedId
-  class EncodedIdFormatError < Hashids::InputError; end
+  class EncodedIdFormatError < ArgumentError; end
 
-  class InvalidAlphabetError < Hashids::AlphabetError; end
+  class InvalidAlphabetError < ArgumentError; end
+
+  class InvalidInputError < ArgumentError; end
 end

data/rbs_collection.yaml

@@ -0,0 +1,26 @@
+# Download sources
+sources:
+  - name: ruby/gem_rbs_collection
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    revision: main
+    repo_dir: gems
+
+# A directory to install the downloaded RBSs
+path: .gem_rbs_collection
+
+gems:
+  - name: encoded_id
+    ignore: true
+  # Skip loading rbs gem's RBS.
+  # It's unnecessary if you don't use rbs as a library.
+  - name: rbs
+    ignore: true
+  - name: rake
+    ignore: true
+  - name: minitest
+    ignore: true
+  - name: standard
+    ignore: true
+  - name: steep
+    ignore: true
+

data/sig/encoded_id.rbs

@@ -1,4 +1,59 @@
 module EncodedId
-  VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  VERSION: ::String
+
+  EncodedIdFormatError: ::ArgumentError
+  InvalidAlphabetError: ::ArgumentError
+  InvalidInputError: ::ArgumentError
+
+  class ReversibleId
+    ALPHABET: ::String
+
+    def initialize: (salt: ::String, ?length: ::Integer, ?split_at: ::Integer, ?alphabet: ::String, ?hex_digit_encoding_group_size: ::Integer) -> void
+
+    # Encode the input values into a hash
+    def encode: (untyped values) -> ::String
+
+    # Encode hex strings into a hash
+    def encode_hex: (untyped hexs) -> ::String
+
+    # Decode the hash to original array
+    def decode: (::String str) -> ::Array[::Integer]
+
+    # Decode hex strings from a hash
+    def decode_hex: (::String str) -> ::Array[::String]
+
+    private
+
+    @encoded_id_generator: ::Hashids
+    @split_regex: ::Regexp
+    @hex_string_separator: ::Integer
+
+    attr_reader salt: ::String
+
+    attr_reader length: ::Integer
+
+    attr_reader human_friendly_alphabet: ::String
+
+    attr_reader split_at: ::Integer | nil
+
+    attr_reader hex_digit_encoding_group_size: ::Integer
+
+    def prepare_input: (untyped value) -> ::Array[::Integer]
+
+    def encoded_id_generator: () -> ::Hashids
+
+    def split_regex: () -> ::Regexp
+
+    def humanize_length: (::String hash) -> ::String
+
+    def convert_to_hash: (::String str) -> ::String
+
+    def map_crockford_set: (::String str) -> ::String
+
+    def integer_representation: (untyped hexs) -> ::Array[::Integer]
+
+    def integers_to_hex_strings: (::Array[::Integer] integers) -> ::Array[::String]
+
+    def hex_string_separator: () -> ::Integer
+  end
 end

data/sig/hash_ids.rbs

@@ -0,0 +1,72 @@
+class Hashids
+  VERSION: ::String
+
+  MIN_ALPHABET_LENGTH: ::Integer
+
+  SEP_DIV: ::Float
+
+  GUARD_DIV: ::Float
+
+  DEFAULT_SEPS: ::String
+
+  DEFAULT_ALPHABET: ::String
+
+  attr_reader salt: ::String
+
+  attr_reader min_hash_length: ::Integer
+
+  attr_reader alphabet: ::String
+
+  attr_reader seps: ::String
+
+  attr_reader guards: untyped
+
+  def initialize: (?::String salt, ?::Integer min_hash_length, ?untyped alphabet) -> void
+
+  def encode: (*(Array[::Integer] | ::Integer) numbers) -> ::String
+
+  def encode_hex: (::String str) -> ::String
+
+  def decode: (::String hash) -> ::Array[::Integer]
+
+  def decode_hex: (::String hash) -> ::Array[::Integer]
+
+  # protected
+
+  def internal_encode: (untyped numbers) -> untyped
+
+  def internal_decode: (untyped hash, untyped alphabet) -> untyped
+
+  def consistent_shuffle: (untyped alphabet, untyped salt) -> untyped
+
+  def hash: (untyped input, untyped alphabet) -> untyped
+
+  def unhash: (untyped input, untyped alphabet) -> untyped
+
+  private
+
+  def setup_alphabet: () -> untyped
+
+  def setup_seps: () -> untyped
+
+  def setup_guards: () -> untyped
+
+  SaltError: ArgumentError
+
+  MinLengthError: ArgumentError
+
+  AlphabetError: ArgumentError
+
+  InputError: ArgumentError
+
+  def validate_attributes: () -> untyped
+
+  def validate_alphabet: () -> (untyped | nil)
+
+  def hex_string?: (untyped string) -> untyped
+
+  def pick_characters: (untyped array, untyped index) -> untyped
+
+  def uniq_characters: (untyped string) -> untyped
+end
+

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: encoded_id
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Stephen Ierodiaconou
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-10-11 00:00:00.000000000 Z
+date: 2022-10-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hashids
@@ -40,10 +40,13 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- Steepfile
 - lib/encoded_id.rb
 - lib/encoded_id/reversible_id.rb
 - lib/encoded_id/version.rb
+- rbs_collection.yaml
 - sig/encoded_id.rbs
+- sig/hash_ids.rbs
 homepage: https://github.com/stevegeek/encoded_id
 licenses:
 - MIT
@@ -66,7 +69,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: EncodedId is a gem for creating reversible obfuscated IDs from numerical