human_token 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5bd2c6de633f5bcebaea72ae7eac1505ac9739cf
+  data.tar.gz: f92d52708f9964826317111ef016158d89311ecb
+SHA512:
+  metadata.gz: 93353224a2123151548107066765c8bd69af4d9400a3ef6276fb886f829d95eb30dcf86219fdd81e75eaf6622573d2f0ac8e8dfe8b4237940b611461f5488fa5
+  data.tar.gz: e5d8e28b1539d023f9a8846a565ef0d0da7267cdc464e0b65eea9d91da6ffa854983ad21c56ee8c340927a200304f2d1fbf09ab3cb7786e521ea30bd0eafd088

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/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.1.1
+  - 2.0.0

data/Gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+gem "minitest"
+gem "guard-minitest",          require: false
+gem "terminal-notifier-guard", require: false
+gem "minitest-reporters"
+
+gemspec

data/Guardfile

@@ -0,0 +1,15 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard :bundler do
+  watch('Gemfile')
+  # Uncomment next line if your Gemfile contains the `gemspec' command.
+  watch(/^.+\.gemspec/)
+end
+
+guard :minitest do
+  # with Minitest::Unit
+  watch(%r{^test/(.*)\/?test_(.*)\.rb$})
+  watch(%r{^lib/(.*/)?([^/]+)\.rb$})     { |m| "test/#{m[1]}test_#{m[2]}.rb" }
+  watch(%r{^test/test_helper\.rb$})      { 'test' }
+end

data/LICENSE.txt

@@ -0,0 +1,3 @@
+HumanToken is dedicated to the public domain by its author, Brian Hempel. No rights are reserved. No restrictions are placed on the use of HumanToken. That freedom also means, of course, that no warrenty of fitness is claimed; use HumanToken at your own risk.
+
+Public domain dedication is explained by the CC0 1.0 summary (and only the summary) at https://creativecommons.org/publicdomain/zero/1.0/

data/README.md

@@ -0,0 +1,142 @@
+# HumanToken
+
+HumanToken is a (relatively) human-friendly token generator. You can create tokens of a given cryptographic strength but without ambiguous characters.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'human_token'
+```
+
+And then execute:
+
+```
+$ bundle
+```
+
+Or install it yourself as:
+
+```
+$ gem install human_token
+```
+
+## Usage
+
+HumanToken uses Ruby's SecureRandom to generate tokens.
+
+```ruby
+require 'human_token'
+
+HumanToken.generate # => "2re9y4mdsh39jy4qqh3eq6tzptz"
+```
+
+Just like SecureRandom, the default is 16 bytes of randomness. However, the token is longer than 16 characters because, well, those 16 bytes aren't binary anymore.
+
+You can specify an alternate number of bytes of randomness.
+
+```ruby
+# 64-bit token
+HumanToken.generate(8) # => "nte4mh95kvxdde"
+```
+
+By default, tokens contain lowercase alphanumeric characters, with the exceptions of `0` `1` `i` `l` `o` `u`. Those characters are excluded to prevent ambiguity. The `i` and `o` are not ambiguous when lowercase, but are excluded anyway so the token can be treated case-insensitively: uppercase `I` and `O` are ambiguous.
+
+The letter `u` is excluded because, if it were included, when generating 128 bit tokens about 1 in every 340 tokens would phonetically drop the f-bomb on the viewer—or even more often (a lot more often!) if we count a "u" proceed by an "f". [Douglas Crockford](http://www.crockford.com/wrmg/base32.html) is the inspiration for excluding "u", though he didn't enumerate the math.
+
+The default tokens are lowercase because lowercase is much easier to read.
+
+## Schemes
+
+Several encoding schemes are provided.
+
+```ruby
+HumanToken.hex         # Lowercase hexadecimal (included for comparison purposes)
+HumanToken.base_30     # Lowercase base 30, no 0 1 I L O U (this is the default scheme)
+HumanToken.base_31     # Lowercase base 31, no 0 1 I L O
+HumanToken.base_32     # Crockford's Base 32: Uppercase, no I L O U
+HumanToken.base_58     # Bitcoin Base 58: Mixed case, no 0 I O l
+HumanToken.new_base_60 # Tantek Çelik's "New Base 60": Mixed case and underscore, no I O l
+HumanToken.base_62     # All 62 mixed case alphanumerics
+```
+
+You can provide a custom scheme.
+
+```ruby
+HumanToken.generate(6, characters: "aeiou")
+# => "iauioieuoaeeeauiauuii"
+```
+
+Internally, HumanToken uses [BaseX](https://github.com/brianhempel/base_x) for encoding. A custom scheme can also be specified by providing a BaseX object.
+
+```ruby
+HumanToken.generate(32, base: BaseX.base(36))
+# => "9KV0FL722DDYQ5IOFIJDB1DT0AIDUID6U0VUBCRC9IK7POQG9S"
+```
+
+For reference, in IRB you can get a list of all the provided schemes with a sample 128 bit token in each.
+
+```
+> HumanToken.samples
+hex         "2c50e3ec571d5d662580e22de852147e"
+base_30     "fwkt9zvwn4ara5n6qfhbmbsvfgr"
+base_31     "7577vd28g58d8s5g84sgc5c6zq"
+base_32     "BSGTEN21DRYMDSG75TDEMDDMKS"
+base_58     "jW9NHFsBv4b2ynHaMa68zy"
+new_base_60 "Fh7HDfRZ_pGwbUMtVF2ttv"
+base_62     "x8SuXOLhXSjAx1jGzSCvzB"
+
+# You can also ask for sample tokens of a given size
+> HumanToken.samples(4)
+hex         "0a91b59b"
+base_30     "cx85466"
+base_31     "un7hxe6"
+base_32     "N9YXAZ3"
+base_58     "pJKN11"
+new_base_60 "wJ5cc_"
+base_62     "DugJc6"
+```
+
+## Other Tidbits
+
+If you ask for 128 bits (16 bytes) of randomness, you are actually getting _at least_ 128 bits. Why?
+
+Consider the default generator. There are thirty "numerals" used in the default scheme (the 36 alphanumerics, minus 0, 1, I, O, L, and U). Each "numeral" in base 30 encodes about 4.9 bits of information. A token of length 26 can encdoe 127.6 bits of information. That's not enough for 128 bits of randomness. A token of length 27 can encode 132.5 bits of information.  Why waste the extra space by encoding only 128 bits in a string that can encode 132.5? Therefore, HumanToken encodes 132.5 bits of randomness.
+
+However, if you don't want to explain to your colleagues why your tokens have "132 bit security" instead of a standard number like 128, then you can ask for exactly 128 bits. Your tokens will be the same length, but the first character will appear less random.
+
+```ruby
+HumanToken.generate(exact_bytes: 16)
+# => "29spx4xsse3cqgr7da7nrasxfc2"
+
+# First character will always be a 2 or 3 in this case
+> 10.times { p HumanToken.generate(exact_bytes: 16) }
+"2va3np2rhc8phqcwfmyy8mm62b6"
+"2nhdf3jxz87qcfx4w2j8gna3f8k"
+"25x5j7eh7k8vfnm372sbayd3brh"
+"2wtxf5mrcw7aaw2hwk8ybpqex4r"
+"2at5knh6aw38a8xaxcr262gnxs4"
+"2bn7a7fx2gq6g8t5cg9yff6qeh8"
+"23cy29jsbmj4w3xj35f6dygrvqp"
+"2575jtkajbtyhx44gksdykjcfsq"
+"29ny2f956jzytxwbt56y2vsea8t"
+"2yrptgvaq6hyywanssgqm6ca6jb"
+```
+
+## License
+
+Public Domain; no rights reserved.
+
+No restrictions are placed on the use of HumanToken. That freedom also means, of course, that no warrenty of fitness is claimed; use HumanToken at your own risk.
+
+Public domain dedication is explained by the CC0 1.0 summary (and only the summary) at https://creativecommons.org/publicdomain/zero/1.0/
+
+
+## Contributing
+
+1. Fork it ( http://github.com/brianhempel/human_token/fork )
+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,10 @@
+require "bundler/gem_tasks"
+
+task :default => :test
+
+desc "Run the tests"
+task :test do
+  Dir.glob(File.expand_path("../test/*.rb", __FILE__)).each do |file|
+    require file
+  end
+end

data/human_token.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'human_token/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "human_token"
+  spec.version       = HumanToken::VERSION
+  spec.authors       = ["Brian Hempel"]
+  spec.email         = ["plasticchicken@gmail.com"]
+  spec.summary       = %q{Tokens for humans: no ambiguous characters! Highly configurable.}
+  spec.description   = spec.summary
+  spec.homepage      = "https://github.com/brianhempel/human_token"
+  spec.license       = "Public Domain"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "base_x", "~> 0.8.0"
+
+  spec.add_development_dependency "bundler", "~> 1.5"
+  spec.add_development_dependency "rake"
+end

data/lib/human_token.rb

@@ -0,0 +1,60 @@
+require 'human_token/version'
+require 'securerandom'
+require 'base_x'
+
+module HumanToken
+  DEFAULTS = { bytes: 16, base: BaseX::Base30L }
+  BASES = [
+    [:hex,         BaseX::Base16L],
+    [:base_30,     BaseX::Base30L],
+    [:base_31,     BaseX::Base31L],
+    [:base_32,     BaseX::CrockfordBase32],
+    [:base_58,     BaseX::BitcoinBase58],
+    [:new_base_60, BaseX::NewBase60],
+    [:base_62,     BaseX::Base62DUL],
+  ]
+
+  def self.generate(*args)
+    options = normalize_generate_options(args, DEFAULTS)
+    base, bytes, exact_bytes = options[:base], options[:bytes], options[:exact_bytes]
+
+    base = BaseX.new(options[:characters]) if options[:characters]
+
+    if exact_bytes
+      base.encode(SecureRandom.random_bytes(exact_bytes))
+    else
+      length = (Math.log(256)/Math.log(base.base)*bytes).ceil
+      token  = base.encode(SecureRandom.random_bytes(bytes + 1))
+      token[-length..-1]
+    end
+  end
+
+  BASES.each do |name, base|
+    define_singleton_method(name) do |*args|
+      options = normalize_generate_options(args, base: base)
+      generate(options)
+    end
+  end
+
+  def self.samples(*args)
+    STDERR.puts samples_string(*args)
+  end
+
+  class << self
+    private
+
+    def normalize_generate_options(args, defaults)
+      defaults.dup.tap do |options|
+        options[:bytes] = args.first if args.first.is_a?(Integer)
+        args.grep(Hash).each {|hash| options.merge!(hash)}
+      end
+    end
+
+    def samples_string(*args)
+      longest_name_length = BASES.sort_by {|name, base| -name.size}.first[0].size
+      BASES.map do |method_name, _|
+        "%-#{longest_name_length}s %s" % [method_name, self.send(method_name, *args).inspect]
+      end.join("\n")
+    end
+  end
+end

data/lib/human_token/version.rb

@@ -0,0 +1,3 @@
+module HumanToken
+  VERSION = "0.9.0"
+end

data/test/test_human_token.rb

@@ -0,0 +1,80 @@
+require 'bundler/setup'
+Bundler.require(:test)
+
+require 'human_token'
+require 'minitest/autorun'
+require 'minitest/reporters'
+MiniTest::Reporters.use! Minitest::Reporters::DefaultReporter.new
+
+class TestHumanToken < Minitest::Test
+  def test_generate
+    token = HumanToken.generate
+    assert_equal 27, token.length
+  end
+
+  def test_generate_with_bytes_given
+    token = HumanToken.generate(8)
+    assert_equal 14, token.length
+  end
+
+  def test_generate_with_exact_bytes_given
+    token = HumanToken.generate(exact_bytes: 8)
+    assert_equal 14, token.length
+  end
+
+  def test_generate_with_different_base
+    token = HumanToken.generate(base: BaseX::Base58)
+    assert_equal 22, token.length
+  end
+
+  def test_floating_point_math_works
+    token = HumanToken.generate(5, base: BaseX.base(32))
+    assert_equal 8, token.length
+  end
+
+  def test_custom_characters
+    token = HumanToken.generate(6, characters: "asdfjkl;")
+    assert_equal 16, token.length
+  end
+
+  def test_base_30
+    token = HumanToken.base_30
+    assert_equal 27, token.length
+    token = HumanToken.base_30(exact_bytes: 32)
+    assert_equal 53, token.length
+  end
+
+  def test_base_31
+    token = HumanToken.base_31
+    assert_equal 26, token.length
+  end
+
+  def test_base_32
+    token = HumanToken.base_32
+    assert_equal 26, token.length
+  end
+
+  def test_base_58
+    token = HumanToken.base_58
+    assert_equal 22, token.length
+  end
+
+  def test_new_base_60
+    token = HumanToken.new_base_60
+    assert_equal 22, token.length
+  end
+
+  def test_base_62
+    token = HumanToken.base_62
+    assert_equal 22, token.length
+  end
+
+  def test_hex
+    token = HumanToken.hex
+    assert_equal 32, token.length
+  end
+
+  def test_samples
+    HumanToken.send(:samples_string) # doesn't error
+  end
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: human_token
+version: !ruby/object:Gem::Version
+  version: 0.9.0
+platform: ruby
+authors:
+- Brian Hempel
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-05-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base_x
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 'Tokens for humans: no ambiguous characters! Highly configurable.'
+email:
+- plasticchicken@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- Guardfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- human_token.gemspec
+- lib/human_token.rb
+- lib/human_token/version.rb
+- test/test_human_token.rb
+homepage: https://github.com/brianhempel/human_token
+licenses:
+- Public Domain
+metadata: {}
+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: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: 'Tokens for humans: no ambiguous characters! Highly configurable.'
+test_files:
+- test/test_human_token.rb