human_readable 0.8.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5307eeacfd4961a43325a641b37da77388aedcb419f1c2bd0ae1021eec63417b
+  data.tar.gz: 44414551a3e4333ab02beb913c69bf8afddce406b2e1701c2f7d79e1150a464d
+SHA512:
+  metadata.gz: 1662e91b1671caf3ac01da210016eb0544d6b82a9eec0f93279eaa9460472bea09fa8ba078d5204551dbb948c81c0a9f874a62d4001c41cfe9cd8c7c2dda38a0
+  data.tar.gz: b728158418c8b4ea875dc80cccc4055107fbf48014821c325b8e76dfbe6c63f38394d57544c8f13909c376e47f45b19e812fc3ca100994ca2a0a42a2d12eaef9

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+Release History
+===============
+
+# 0.8.0
+* Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Mack Earnhardt
+
+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,67 @@
+# HumanReadable
+
+Human readable random tokens with limited ambiguous characters.
+
+Focus is readability in poor conditions or from potentially damaged printed documents rather than cryptographic uses.
+Despite this focus, SecureRandom is used to help avoid collisions.
+
+Inspired by Douglas Crockford's [Base 32](https://www.crockford.com/base32.html), but attempts to correct mistakes by substituting the most likely misread.
+To make substitution safer, the token includes a check character generated using the [Luhn mod N algorithm](https://en.wikipedia.org/wiki/Luhn_mod_N_algorithm).
+Default character set is all caps based on this published study on [text legibility](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC2016788/), which matches Crockford as well.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'human_readable'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install human_readable
+
+## Usage
+
+For 10 characters of the default character set, use `HumanReadable.generate`.
+For other lengths (2..x), use `HumanReadable.generate(output_size: 50)`.
+
+## Configuration
+
+* Change available characters and substitution by manipulating `substitution_hash`
+* To include non-default characters, add a self-reference to the hash
+* Inspect available characters using `HumanReadable.charset`
+* For convenience, numbers and symbols are allowed in the hash and are translated to characters during usage
+
+**CAUTION:** Changing `substitution_hash` keys alters the check character, invalidating previous tokens.
+
+
+    HumanReadable.configure do |c|
+      # Default: substitution_hash = { I: 1, L: 1, O: 0, U: :V }
+
+      # Modifications
+      c.substitution_hash[:B] = 8
+      c.substitution_hash[:U] = nil
+      c.substitution_hash['$'] = '$'
+      # or equivalently
+      c.substitution_hash = { I: 1, L: 1, O: 0, U: nil, B: 8, '$' => '$'}
+    end
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/MacksMind/human_readable.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/human_readable.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+# Copyright 2020 Mack Earnhardt
+
+require 'human_readable/version'
+require 'ostruct'
+require 'securerandom'
+
+# Human readable random tokens with no ambiguous characters
+module HumanReadable
+  # +#generate+ output_size must be >= 2 due to check character
+  class MinSizeTwo < StandardError; end
+
+  class << self
+    # Yields block for configuration
+    #
+    #   HumanReadable.configure do |c|
+    #     c.substitution_hash[:B] = 8
+    #     c.substitution_hash[:U] = nil
+    #     c.substitution_hash['$'] = '$'
+    #     # or equivalently
+    #     c.substitution_hash = { I: 1, L: 1, O: 0, U: nil, B: 8, '$' => '$'}
+    #   end
+    #
+    # DEFAULT:
+    #   substitution_hash: { I: 1, L: 1, O: 0, U: :V }
+    #
+    # Specified keys won't be used during generation, and values will be substituted during
+    # validation, increasing the likelihood that a misread character can be restored. Extend
+    # or replace the substitutions to use a different character set. For convenience, numbers
+    # and symbols are allowed in the hash and are translated to characters during usage.
+    # Alter as needed per examples below.
+    #
+    # *CAUTION:* Changing substitution_hash keys alters the check character, invalidating previous tokens.
+    def configure
+      yield(configuration)
+    end
+
+    # Generates a random token of the requested size
+    #
+    # Minimum size is 2 since the last character is a check character
+    def generate(output_size: 10)
+      raise(MinSizeTwo) if output_size < 2
+
+      (token = generate_random(output_size - 1)) + check_character(token)
+    end
+
+    # Clean and validate a candidate token
+    #
+    # * Upcases
+    # * Applies substitutions
+    # * Remove characters not in available character set
+    # * Validates the check character
+    #
+    # Return value: Valid token or nil
+    def valid_token?(input)
+      return unless input.is_a?(String)
+
+      codepoints = input.upcase.tr(trans_from, trans_to).chars.map! { |c| charset.index(c) }
+      codepoints.compact!
+
+      return if codepoints.size < 2
+
+      array =
+        codepoints.reverse.each_with_index.map do |codepoint, i|
+          codepoint *= 2 if i.odd?
+          codepoint / charset_size + codepoint % charset_size
+        end
+
+      codepoints.map { |codepoint| charset[codepoint] }.join if (array.sum % charset_size).zero?
+    end
+
+    # Characters available for token generation
+    #
+    # Manipulate by configuring +substitution_hash+
+    #
+    # DEFAULT: All number and uppercase letters except for ILOU
+    def charset
+      @charset ||= (('0'..'9').to_a + ('A'..'Z').to_a - trans_from.chars + trans_to.chars - nil_substitutions).uniq
+    end
+
+  private
+
+    def configuration
+      @configuration ||= OpenStruct.new(
+        substitution_hash: { I: 1, L: 1, O: 0, U: :V }
+      )
+    end
+
+    # Generates a random string of the requested length from the charset
+    #
+    # We could use one of the below routines in +#generate+, but the first
+    # increases the chances of token collisions and the second is too slow.
+    #
+    #   Array.new(random_size) { charset.sample }
+    #   # or
+    #   Array.new(random_size) { charset.sample(random: SecureRandom) }
+    #
+    # Instead we attempt to optimize the number of bytes generated with each
+    # call to SecureRandom.
+    def generate_random(random_size)
+      return '' unless random_size.positive?
+
+      codepoints = []
+
+      while codepoints.size < random_size
+        bytes_needed = ((random_size - codepoints.size) * byte_multiplier).ceil
+
+        codepoints +=
+          begin
+            array =
+              SecureRandom
+              .random_bytes(bytes_needed)
+              .unpack1('B*')
+              .scan(scan_regexp)
+              .map! { |bin_string| bin_string.to_i(2) }
+            array.select { |codepoint| codepoint < charset_size }
+          end
+      end
+
+      codepoints[0, random_size].map { |codepoint| charset[codepoint] }.join
+    end
+
+    # Compute check character using Luhn mod N algorithm
+    #
+    # *CAUTION:* Changing substitution_hash keys alters the output
+    def check_character(input)
+      array =
+        input.chars.reverse.each_with_index.map do |c, i|
+          d = charset.index(c)
+          d *= 2 if i.even?
+          d / charset_size + d % charset_size
+        end
+
+      mod = (charset_size - array.sum % charset_size) % charset_size
+
+      charset[mod]
+    end
+
+    def char_bits
+      @char_bits ||= (charset_size - 1).to_s(2).size
+    end
+
+    def scan_regexp
+      @scan_regexp ||= /.{#{char_bits}}/
+    end
+
+    def byte_multiplier
+      @byte_multiplier ||=
+        begin
+          bit_multiplier = char_bits / 8.0
+          # Then extra 1.1 helps performance due to randomness of misses
+          miss_percentage = 2**char_bits * 1.0 / charset_size * 1.1
+          bit_multiplier * miss_percentage
+        end
+    end
+
+    def charset_size
+      @charset_size ||= charset.size
+    end
+
+    def nil_substitutions
+      @nil_substitutions ||=
+        begin
+          array = configuration.substitution_hash.each.map { |k, v| k if v.nil? }
+          array.compact!
+          array.map!(&:to_s)
+          array.map!(&:upcase)
+        end
+    end
+
+    def trans_from
+      @trans_from ||=
+        begin
+          array = configuration.substitution_hash.each.map { |k, v| k unless v.nil? }
+          array.compact!
+          array.map!(&:to_s)
+          array.map!(&:upcase)
+          array.join
+        end
+    end
+
+    def trans_to
+      @trans_to ||=
+        begin
+          array = configuration.substitution_hash.values
+          array.compact!
+          array.map!(&:to_s)
+          array.map!(&:upcase)
+          array.join
+        end
+    end
+  end
+end

data/lib/human_readable/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Copyright 2020 Mack Earnhardt
+
+module HumanReadable
+  # Gem version
+  VERSION = '0.8.0'
+  public_constant :VERSION
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: human_readable
+version: !ruby/object:Gem::Version
+  version: 0.8.0
+platform: ruby
+authors:
+- Mack Earnhardt
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2020-08-15 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Human readable random tokens with no ambiguous characters
+
+  Tranlates invalid characters to their most likely original value
+  and validates using a checksum.
+email:
+- mack@agilereasoning.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- "./CHANGELOG.md"
+- "./LICENSE.txt"
+- "./README.md"
+- lib/human_readable.rb
+- lib/human_readable/version.rb
+homepage: https://github.com/MacksMind/human_readable
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/MacksMind/human_readable
+  source_code_uri: https://github.com/MacksMind/human_readable
+  changelog_uri: https://github.com/MacksMind/human_readable/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.4.1
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key:
+specification_version: 4
+summary: Human readable random tokens with no ambiguous characters
+test_files: []