bonio-scatter_swap 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 45d027873e1e1d8ae6967520352c54f93587576e6ee7b50d0c5b923901061fbb
+  data.tar.gz: 0fec3718818cc64f0919f7f2b3b28b3abc145d80caa27174fda70151ae773957
+SHA512:
+  metadata.gz: 8adea79c3f2ef9b61dd26baa4930ea7b7a293e0c799be1a6f1892e61ca5661cac7db8350ea2f0dea5bf2af9a133a44e35d271c3d540549d7b566565bdcae424f
+  data.tar.gz: cd50a3dbc1e6fa29601742e710757b44ce16ae4de597ecc638d89b3119a38ea2fa37530ed3778629544b01815c251959179d6ef8ba26963c8480b2830e1530d1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format doc

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in scatter_swap.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Nathan and David Amick
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,105 @@
+# ScatterSwap
+
+This is the integer hashing function behind [obfuscate_id](https://github.com/namick/obfuscate_id).
+
+> Designing a hash function is a bit of a black art and
+> being that I don't have math background, I must resort
+> to this simplistic swaping and scattering of array elements.
+
+> After writing this and reading/learning some elemental hashing techniques,
+> I realized that this library is an example of what is known as a [minimal perfect hash function](http://en.wikipedia.org/wiki/Perfect_hash_function#Minimal_perfect_hash_function).
+
+> I welcome all improvements via pull-requests :-)
+
+> If you have some comments or suggestions, please contact me at `github@nathanamick.com` - nathan amick
+
+## Goals
+
+We want to transform an integer into another random looking integer and then reliably tranform it back.
+
+It will turn the number `3` into `2356513904`, and it can then reliably reverse that scrambled `2356513904` number back into `3`
+
+We also want sequential integers to become non-sequential.
+
+So for example it will turn `7001, 7002, 7003` into `5270192353, 7107163820, 3296163828`, and back again.
+
+Please note, this is not encryption or related to security in any way.  It lightly obfuscates an integer in a reversible way.
+
+## Usage
+
+Pass a number (as an integer or string) to the 'hash' method and it will return an obfuscated version of it.
+
+    ScatterSwap.hash(1).to_i
+    #=> 4517239960
+
+Pass that obfuscated version in and it will return the original (as a zero padded string).
+
+    ScatterSwap.reverse_hash(4517239960).to_i
+    #=> 1
+
+
+*Because this was originally built for urls like this `example.com/users/00000000001` it outputs strings.  This is why the examples above have `to_i` tacked on to them.  Since extracting it to its own library, that may not make sense anymore.  I'm considering output the same type as it is input.  Thoughts?*
+
+## How it works
+
+This library is built for integers that can be expressed with 10 digits.
+It zero pads smaller numbers.
+
+The number 1 is expressed with:
+
+    0000000001
+
+The biggest number it can deal with is 10 billion - 1:
+
+    9999999999
+
+Since we are working with a limited sequential set of input integers, 10 billion,
+this algorithm will suffice for simple id obfuscation for many web apps.
+
+The largest value that Ruby on Rails default id, Mysql INT type, is just over 2 billion (2147483647)
+which is the same as 2 to the power of 31 minus 1, but considerably less than 10 billion.
+
+## Strategies
+
+ScatterSwap is an integer hash function designed to have:
+
+- zero collisions ( http://en.wikipedia.org/wiki/Perfect_hash_function )
+- achieve avalanche ( http://en.wikipedia.org/wiki/Avalanche_effect )
+- reversible
+
+We do that by combining two distinct strategies.
+
+1. Scattering - whereby we take the whole number, slice it up into 10 digits
+and rearange their places, yet retaining the same 10 digits.  This allows
+us to preserve the sum of all the digits, regardless of order.  This sum acts
+as a key to reverse this scattering effect.
+
+2. Swapping - when dealing with many sequential numbers that we don't want
+to look similar, scattering wont do us much good because so many of the
+digits are the same; it deoesn't help to scatter 9 zeros around, so we need
+to swap out each of those zeros for something else.. something different
+for each place in the 10 digit array; for this, we need a map so that we
+can reverse it.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'bonio-scatter_swap'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install bonio-scatter_swap
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bonio-scatter_swap.gemspec

@@ -0,0 +1,36 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'scatter_swap/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'bonio-scatter_swap'
+  spec.version       = ScatterSwap::VERSION
+  spec.authors       = ['khiav reoy']
+  spec.email         = ['mrtmrt15xn@yahoo.com.tw']
+
+  spec.description   = %q{ScatterSwap is an integer hash function designed to have zero collisions, achieve avalanche, and be reversible.}
+  spec.summary       = %q{Minimal perfect hash function for 10 digit integers}
+  spec.homepage      = 'https://github.com/khiav223577/scatter_swap'
+  spec.license       = 'MIT'
+
+  # Prevent pushing this gem to RubyGems.org by setting 'allowed_push_host', or
+  # delete this section to allow pushing this gem to any host.
+  # if spec.respond_to?(:metadata)
+  #   spec.metadata['allowed_push_host'] = "TODO: Set to 'http://mygemserver.com'"
+  # else
+  #   raise "RubyGems 2.0 or newer is required to protect against public gem pushes."
+  # end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject{|f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}){|f| File.basename(f) }
+  spec.require_paths = ['lib']
+  spec.metadata      = {
+    'homepage_uri'      => 'https://github.com/khiav223577/scatter_swap',
+    'changelog_uri'     => 'https://github.com/khiav223577/scatter_swap/blob/master/CHANGELOG.md',
+    'source_code_uri'   => 'https://github.com/khiav223577/scatter_swap',
+    'documentation_uri' => 'https://www.rubydoc.info/gems/scatter_swap',
+    'bug_tracker_uri'   => 'https://github.com/khiav223577/scatter_swap/issues',
+  }
+end

data/lib/bonio-scatter_swap.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'scatter_swap'

data/lib/scatter_swap.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'scatter_swap/version'
+require 'scatter_swap/hasher'
+
+module ScatterSwap
+  def self.hash(plain_integer, spin = 0, length = 10)
+    Hasher.new(plain_integer, spin, length).hash
+  end
+
+  def self.reverse_hash(hashed_integer, spin = 0, length = 10)
+    Hasher.new(hashed_integer, spin, length).reverse_hash
+  end
+end

data/lib/scatter_swap/hasher.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'scatter_swap/swapper'
+
+module ScatterSwap
+  class Hasher
+    DIGITS = (0..9).to_a.freeze
+
+    attr_accessor :working_array
+
+    def initialize(original_integer, spin = 0, length = 10)
+      @original_integer = original_integer
+      @spin = spin
+      @length = length
+      zero_pad = original_integer.to_s.rjust(length, '0')
+      @working_array = zero_pad.chars.map(&:to_i)
+    end
+
+    # obfuscates an integer up to @length digits in length
+    def hash
+      swap
+      scatter
+      @working_array.join
+    end
+
+    # de-obfuscates an integer
+    def reverse_hash
+      unscatter
+      unswap
+      @working_array.join
+    end
+
+    def swapper_map(index)
+      Swapper.instance(@spin).generate(index)
+    end
+
+    # Using a unique map for each of the ten places,
+    # we swap out one number for another
+    def swap
+      @working_array = @working_array.map.with_index do |digit, index|
+        swapper_map(index)[digit]
+      end
+    end
+
+    # Reverse swap
+    def unswap
+      @working_array = @working_array.map.with_index do |digit, index|
+        swapper_map(index).rindex(digit)
+      end
+    end
+
+    # Rearrange the order of each digit in a reversible way by using the
+    # sum of the digits (which doesn't change regardless of order)
+    # as a key to record how they were scattered
+    def scatter
+      sum_of_digits = @working_array.inject(:+).to_i
+      @working_array = @length.times.map do
+        @working_array.rotate!(@spin ^ sum_of_digits).pop
+      end
+    end
+
+    # Reverse the scatter
+    def unscatter
+      scattered_array = @working_array
+      sum_of_digits = scattered_array.inject(:+).to_i
+      @working_array = []
+      @working_array.tap do |unscatter|
+        @length.times do
+          unscatter.push scattered_array.pop
+          unscatter.rotate! (sum_of_digits ^ @spin) * -1
+        end
+      end
+    end
+  end
+end

data/lib/scatter_swap/run.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'scatter_swap'
+
+# This file is spike code and is not part of the library
+# 
+# While developing this, I used this file to visualize what was going on with the numbers
+#
+# You can uncomment various methods at the bottom and then run it like this:
+#
+# watch -n1 ruby run_scatter_swap.rb
+# 
+# tweak the code a bit and see instant visual changes in the generated numbers
+
+def visualize_scatter_and_unscatter
+  # change this number to experiment with different values
+  rotations = 99
+
+  original = ScatterSwap.arrayify(123456789)
+  scattered = []
+  unscattered = []
+  puts original.join
+  puts "rotate!(#{rotations})"
+  10.times do
+    puts original.rotate!(rotations).join + "->" + scattered.push(original.pop).join
+  end
+  puts "scattered"
+  puts scattered.join
+  10.times do
+    puts unscattered.push(scattered.pop).join + "->" + unscattered.rotate!(rotations * -1).join
+  end
+
+  puts unscattered.join
+end
+
+
+def visualize_swapper_map
+  puts "swapper map"
+  10.times do |index|
+    key = 1
+    puts ScatterSwap.swapper_map(index).join.to_s
+  end
+end
+
+def visualize_hash
+  puts "hash"
+  40.times do |integer|
+    output = "|"
+    3.times do |index|
+      output += " #{(integer + (123456789 * index)).to_s.rjust(5, ' ')}"
+      output += " => #{hashed = ScatterSwap.hash(integer + (123456789 * index) ) }"
+      output += " => #{ScatterSwap.reverse_hash(hashed) } |"
+    end
+    puts output
+  end
+end
+
+
+def visualize_scatter
+  puts "original      scattered     unscattered"
+  20.times do |integer|
+    output = ""
+    2.times do |index|
+      original = ScatterSwap.arrayify(integer + (123456789 * index))
+      scattered = ScatterSwap.scatter(original.clone)
+      unscattered = ScatterSwap.unscatter(scattered.clone)
+      output += "#{original.join}" 
+      output += " => #{scattered.join}"
+      output += " => #{unscattered.join}    |    "
+    end
+    puts output
+  end
+end
+
+
+# find hash for lots of spins
+def visualize_spin
+  2000.times do |original|
+    hashed_values = []
+    9000000000.times do |spin|
+      hashed =  ScatterSwap.hash(original, spin)
+      if hashed_values.include? hashed
+        puts "collision: #{original} - #{spin} - #{hashed}"
+        break
+      end
+      hashed_values.push hashed
+    end
+  end
+end
+
+#visualize_spin
+#visualize_hash
+#visualize_scatter_and_unscatter
+#visualize_scatter
+#visualize_swapper_map

data/lib/scatter_swap/swapper.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+#
+# We want a unique map for each place in the original number
+module ScatterSwap
+  class Swapper
+    @all_swapper_maps = {}
+
+    class << self
+      def instance(spin)
+        @all_swapper_maps[spin] ||= new(spin)
+      end
+    end
+
+    DIGITS = (0..9).to_a.freeze
+
+    def initialize(spin)
+      @spin = spin
+      @caches = {}
+    end
+
+    def generate(index)
+      @caches[index] ||= generate_without_cache(index)
+    end
+
+    private
+
+    def generate_without_cache(index)
+      array = DIGITS.dup
+      sum = 0
+      10.times.map.with_index do |i|
+        sum = (sum + ((index + i) ^ @spin) - 1) % (10 - i)
+        next array.delete_at(sum)
+      end
+    end
+  end
+end

data/lib/scatter_swap/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ScatterSwap
+  VERSION = '1.0.0'
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: bonio-scatter_swap
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- khiav reoy
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2019-12-11 00:00:00.000000000 Z
+dependencies: []
+description: ScatterSwap is an integer hash function designed to have zero collisions,
+  achieve avalanche, and be reversible.
+email:
+- mrtmrt15xn@yahoo.com.tw
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bonio-scatter_swap.gemspec
+- lib/bonio-scatter_swap.rb
+- lib/scatter_swap.rb
+- lib/scatter_swap/hasher.rb
+- lib/scatter_swap/run.rb
+- lib/scatter_swap/swapper.rb
+- lib/scatter_swap/version.rb
+homepage: https://github.com/khiav223577/scatter_swap
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/khiav223577/scatter_swap
+  changelog_uri: https://github.com/khiav223577/scatter_swap/blob/master/CHANGELOG.md
+  source_code_uri: https://github.com/khiav223577/scatter_swap
+  documentation_uri: https://www.rubydoc.info/gems/scatter_swap
+  bug_tracker_uri: https://github.com/khiav223577/scatter_swap/issues
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Minimal perfect hash function for 10 digit integers
+test_files: []