mortal-token 0.0.1 → 0.1.0

data/README.rdoc

@@ -3,33 +3,38 @@
 MortalToken is a library for creating tokens that self-destruct after a specified time. No need to store and look up the 
 token; it is self-verifying and self-expiring.
 
-I found myself wanting simple, secure (never a good mix), and not necessarily encrypted auth tokens for some Sinatra apps. 
-I wanted them to expire, but didn't want to keep track of them. Not finding anything, this library emerged. The default lifespan 
-is two of your Earth days. This does *not* mean "48 hours from when it was created". It means that the key will be valid throughout 
-"today" and "tomorrow". If the lifespan were one day, a key created at 23:59 would expire at 00:00.
+The default lifespan is two of your Earth days. This does *not* mean "48 hours from when it was created". It means that 
+the key will be valid throughout "today" and "tomorrow". If the lifespan were one day, a key created at 23:59 would expire 
+in one minute at 00:00.
+
+My original use case was login auth tokens for some simple Sinatra apps. I can also see it being useful for API auth.
+Of course there are potential uses outside of HTTP, too.
 
 Steps:
 
 1. Generate a new token
 2. Give the client the resulting hash and salt
-3. *crickets*
+3. Time passes
 4. Receive a hash and salt from client
-5. Reconstitute the token from the salt, and test if the hashes match
+5. Reconstitute the token from the salt, and test if the hashes match. If not, the token has expired (or was forged).
 
 Read the full documentation at {jordanhollinger.com/docs/mortal-token/}[http://jordanhollinger.com/docs/mortal-token/].
 
-== Disclaimer
+== Warning
+
+This is, at best, alpha-quality software. It "works" in that it doesn't usually blow up, but it is not guaranteed to be "right".
+Don't use it in production, or at least not in any important production. May contain traces of peanut oil.
 
-This is not intended to be the most secure thing ever, but for all I know it's less secure than I think. Suggestions and 
-pull requests are welcomed.
+== Install
 
-Also, it is very early and the API may go through significant changes.
+  [sudo] gem install mortal-token
 
-== Use
+Or add it to your Gemfile
+  gem "mortal-token"
 
-Though my example is a Sinatra app, it need not be. In fact, it needn't have anything to do with the Web. It's useful
-anytime you want a self-contained, self-expiring token (w/ salt).
+== Example with Sinatra
 
+  require 'sinatra'
   require 'mortal-token'
 
   # You MUST set a secret key! Otherwise, anyone who looks at the source code will be able to forge tokens.
@@ -37,50 +42,51 @@ anytime you want a self-contained, self-expiring token (w/ salt).
 
   post '/login' do
     if login_ok?
-      # Create a brand new token. Store the resulting hash and salt.
       token = MortalToken.new
       session[:token] = token.hash
       session[:salt] = token.salt
-
       redirect '/secret'
     end
   end
 
   get '/secret' do
-    # Attempt to reconstitute the original token, using the salt
     token = MortalToken.new(session[:salt])
-
-    # Test if the token still is (or ever was) valid
     if token == session[:token]
-      'Welcome!'
+      'Nice token!'
     else
-      'Go away!'
+      'Your token is expired or forged!'
     end
   end
 
-== Checking tokens
-
-These are all valid means of checking a token's validity. In this case, they will all return true. == and === are treated the same.
-
-  token_a = MortalToken.new
-  token_b = MortalToken.new(token_a.salt)
+== Checking token validity
 
-  token_a == token_b
-  token_a == token_b.to_s
-  token_a == token_b.hash
-  token_a.to_s == token_b.to_s
-  token_a.hash == token_b.hash
-  token_a.to_s == token_b.hash
+A token's == and === methods accept another token or a hash. In the example above, an attempt has been made to reconstitute
+the original token (using it's salt) on the left. If successful, it will be able to regenerate the hash on the right. But if
+too much time has passed, the hashes will differ and we can conclude that the token has expired.
 
 == Tweak token parameters
 
 You may tweak certain parameters of the library in order to make it more secure, less, faster, etc.
 These are the defaults (see the MortalToken class for documentation about each parameter):
 
-  MortalCoil.rounds = 5
-  MortalCoil.valid_across = 2
-  MortalCoil.max_salt_length = 50
-  MortalCoil.min_salt_length = 10
+  MortalToken.rounds = 5            # rounds of hashing
+  MortalToken.units = :days         # or :hours, :minutes
+  MortalToken.valid_across = 2      # tokens are valid across N units
+  MortalToken.max_salt_length = 50
+  MortalToken.min_salt_length = 10
+
+== Multiple configurations
+
+Your application may want to use MortalTokens in various contexts, where the same parameters may not make sense (probably units and valid_across).
+You may define different scopes and give them each their own config. Always define the default scope first (as above). Other scopes will inherit
+its secret.
+
+  MortalToken.config(:foo) do |config|
+    config.units = :minutes
+    config.valid_across = 10
+  end
+
+  token = MortalToken.use(:foo).token
 
 == License
 Copyright 2012 Jordan Hollinger

data/lib/mortal-token.rb

@@ -1,5 +1,7 @@
 require 'date'
+require 'time'
 require 'digest/sha2'
 require 'mortal-token/version'
+require 'mortal-token/token'
+require 'mortal-token/configuration'
 require 'mortal-token/mortal-token'
-require 'mortal-token/defaults'

data/lib/mortal-token/configuration.rb

@@ -0,0 +1,52 @@
+class MortalToken
+  # Holds a specific a configuration of parameters
+  class Configuration
+    RAND_SEEDS = [(0..9), ('a'..'z'), ('A'..'Z')].map(&:to_a).flatten # :nodoc;
+
+    # The configuration's name
+    attr_reader :name
+    # The master secret token (Keep it secret! Keep it safe!). Changing this will invalidate all existing tokens.
+    attr_accessor :secret
+    # The number of encryption rounds. Defaults to 5. Changing this will invalidate existing tokens.
+    attr_accessor :rounds
+    # The units that life is measured in - :days, :hours or :minutes
+    attr_reader :units
+    # The number of units tokens will be valid across. Defaults to 2, which (for :days) prevents a
+    # token generated at 23:59 from expiring at 00:00. Changing this will invalidate existing tokens.
+    attr_accessor :valid_across
+    # The maximum salt length, defaults to 50
+    attr_accessor :max_salt_length
+    # The minimum salt length, defaults to 10
+    attr_accessor :min_salt_length
+
+    # Instantiates a new Configuration object default values
+    def initialize(name)
+      @name = name
+      @rounds = 5
+      @units = :days
+      @valid_across = 2
+      @max_salt_length = 50
+      @min_salt_length = 10
+      # A temporary secret key. Use your own!!
+      @secret = CONFIGS[:default] ? CONFIGS[:default].salt : self.salt
+    end
+
+    # Return a new token using this configuration
+    def token(salt=nil, time=nil)
+      Token.new(salt, time, self)
+    end
+
+    # Set the units that life is measured in - :days, :hours or :minutes
+    def units=(unit)
+      raise ArgumentError, "MortalToken.units must be one of #{UNITS.keys.join(', ')}" unless UNITS.keys.include? unit
+      @units = unit
+    end
+
+    # Returns a random string of between min_salt_length and max_salt_length alphanumeric charachters
+    def salt
+      max_length = [self.min_salt_length, rand(self.max_salt_length + 1)].max
+      pool_size = RAND_SEEDS.size
+      (0..max_length).map { RAND_SEEDS[rand(pool_size)] }.join('')
+    end
+  end
+end

data/lib/mortal-token/mortal-token.rb

@@ -1,76 +1,27 @@
 # A token hash that "self-destructs" after a certain time.
 class MortalToken
-  # Seeds for generating random strings
-  RAND_SEEDS = [(0..9), ('a'..'z'), ('A'..'Z')].map(&:to_a).flatten
+  CONFIGS = {} # :nodoc:
+  UNITS = {days: {increment: 1, format: '%Y-%m-%d'}, hours: {increment: 3600, format: '%Y-%m-%d_%H'}, minutes: {increment: 60, format: '%Y-%m-%d_%H:%M'}} # :nodoc:
 
   class << self
-    # The master secret token (Keep it secret! Keep it safe!). Changing this will invalidate all existing tokens.
-    attr_accessor :secret
-    # The number of encryption rounds. Defaults to 5. Changing this will invalidate existing tokens.
-    attr_accessor :rounds
-    # The number of days tokens will be valid across. Defaults to 2, which prevents a
-    # token generated at 23:59 from expiring at 00:00. Changing this will invalidate existing tokens.
-    attr_accessor :valid_across
-    # The maximum salt length, defaults to 50
-    attr_accessor :max_salt_length
-    # The minimum salt length, defaults to 10
-    attr_accessor :min_salt_length
-
-    # Returns a random string of between min_salt_length and max_salt_length alphanumeric charachters
-    def salt
-      max_length = rand(self.max_salt_length + 1)
-      max_length = self.min_salt_length if max_length < self.min_salt_length
-      pool_size = RAND_SEEDS.size
-      (0..max_length).map { RAND_SEEDS[rand(pool_size)] }.join('')
+    # Returns a new Token. Also alised to #token.
+    def new(salt=nil, time=nil)
+      config.token(salt, time)
     end
-  end
-
-  # The token's salt
-  attr_reader :salt
-
-  # To create a brand new token, do *not* pass any arguments.
-  #
-  # If you want to validate a hash from an existing token, pass
-  # the existing token's salt. You should usually leave "start_date" alone.
-  def initialize(salt=nil, start_date=nil)
-    @salt = salt || MortalToken.salt
-    @start_date = start_date || Date.today
-  end
-
-  # Returns the hash value of the token
-  def hash
-    val = [MortalToken.secret, salt, @start_date, end_date].join('_')
-    MortalToken.rounds.times { val = Digest::SHA512.hexdigest(val) }
-    val
-  end
 
-  # Alias to MortalToken::Token.hash
-  def to_s
-    hash
-  end
-
-  # Tests this token against another token or token hash
-  def ==(other_token_or_hash)
-    other_hash = other_token_or_hash.to_s
-    (earliest_date).upto(@start_date) do |date|
-      guess = MortalToken.new(salt, date)
-      return true if guess.to_s == other_hash
+    # Returns a new or existing MortalToken::Configuration. If you pass a block, it will pass it the config object.
+    # If it's a new config, it will inherit the default settings.
+    def config(name=:default)
+      config = (CONFIGS[name] ||= Configuration.new(name))
+      yield config if block_given?
+      config
     end
-    return false
-  end
-
-  alias_method :===, :==
 
-  private
+    alias_method :use, :config
 
-  # Returns the end date of this token
-  def end_date
-    @start_date + (MortalToken.valid_across - 1)
-  end
-
-  # Returns the earliest possible date this token could have been valid.
-  # Only useful when checking for validity.
-  def earliest_date
-    @start_date - (MortalToken.valid_across - 1)
+    # Alias all other methods to the default Configuration
+    def method_missing(method, *args, &block)
+      config.send(method, *args, &block)
+    end
   end
 end

data/lib/mortal-token/token.rb

@@ -0,0 +1,66 @@
+class MortalToken
+  class Token
+    # The token's salt
+    attr_reader :salt
+    attr_accessor :config
+
+    # To create a brand new token, do *not* pass any arguments. To validate a hash from
+    # an existing token, pass the existing token's salt.
+    def initialize(salt=nil, start_time=nil, config=nil)
+      @config = config || MortalToken.config
+      @salt = salt || config.salt
+      @start_time = start_time || (config.units == :days ? Date.today : Time.now.utc)
+    end
+
+    # Returns the hash value of the token
+    def hash
+      @hash ||= (0..config.rounds-1).inject("#{config.secret}_#{salt}_#{end_time.strftime(strfmt)}") do |val, i|
+        Digest::SHA512.hexdigest(val)
+      end
+    end
+
+    alias_method :to_s, :hash
+
+    # Tests this token against another token or token hash
+    def ==(other_token_or_hash)
+      each_time do |time|
+        guess = config.token(salt, time)
+        return true if guess.to_s == other_token_or_hash.to_s
+      end
+      return false
+    end
+
+    alias_method :===, :==
+
+    private
+
+    # Iterates over each possible time unit and passes it to the block
+    def each_time(&block)
+      time = earliest_time
+      while time <= end_time
+        block.call(time)
+        time += increment
+      end
+    end
+
+    # Returns the end date/time of this token
+    def end_time
+      @start_time + (config.valid_across - 1) * increment
+    end
+
+    # Returns the earliest possible date/time this token could have been valid.
+    def earliest_time
+      @start_time - (config.valid_across - 1) * increment
+    end
+
+    # Returns the incrementor for the configured unit
+    def increment
+      UNITS[config.units][:increment]
+    end
+
+    # Returns the string formater for the configured unit
+    def strfmt
+      UNITS[config.units][:format]
+    end
+  end
+end

data/lib/mortal-token/version.rb

@@ -1,4 +1,4 @@
 class MortalToken
   # Library version
-  VERSION = '0.0.1'
+  VERSION = '0.1.0'
 end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 0
   - 1
-  version: 0.0.1
+  - 0
+  version: 0.1.0
 platform: ruby
 authors: 
 - Jordan Hollinger
@@ -14,11 +14,11 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-08-02 00:00:00 -04:00
+date: 2012-08-03 00:00:00 -04:00
 default_executable: 
 dependencies: []
 
-description: A simple library for generating self-contained, self-destructing tokens
+description: An EXPERIMENTAL library for generating self-contained, self-destructing tokens
 email: jordan@jordanhollinger.com
 executables: []
 
@@ -28,9 +28,10 @@ extra_rdoc_files: []
 
 files: 
 - lib/mortal-token.rb
-- lib/mortal-token/defaults.rb
 - lib/mortal-token/mortal-token.rb
+- lib/mortal-token/token.rb
 - lib/mortal-token/version.rb
+- lib/mortal-token/configuration.rb
 - README.rdoc
 - LICENSE
 has_rdoc: true
@@ -64,6 +65,6 @@ rubyforge_project:
 rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
-summary: Generate self-destructing tokens
+summary: Generate self-destructing tokens (experimental)
 test_files: []
 

data/lib/mortal-token/defaults.rb

@@ -1,10 +0,0 @@
-class MortalToken
-  # Set defaults
-  self.rounds = 5
-  self.valid_across = 2
-  self.max_salt_length = 50
-  self.min_salt_length = 10
-  # Set a temporary secret key. You should set your own consistent key.
-  # Otherwise, existing tokens will be invalidated each time the library is loaded.
-  self.secret = self.salt
-end