toktok 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e16666f292ece7bb076c8ed7672f4141102b2afc
-  data.tar.gz: a99deed7551d520bec1d258d70d9e4a356a68130
+  metadata.gz: 36cfc1bad83de1c2e52e5d88aacb87736494dba2
+  data.tar.gz: b2c0cd4d24b8c645914bef1c330339f4e21b3de8
 SHA512:
-  metadata.gz: 38b8a5680cf95497c2ef012a9f32573d2f8d6627462da97b39eca53a49c651d75f7cd66499e68f5abb9d31cbe5fa20288734eb3afea5558c60d32810fdb4fc87
-  data.tar.gz: 9f3b3878cc38ff13e1c8253102e9fbc33155f1e0881016a67e4da89f0f95a351c5324a36be27b6499a4c0411087e76ec212c9c1e703225468f970083e4969dd3
+  metadata.gz: 165c1721d1a581d28eb3f85a3c07a75bb7e1cc812cc23a6a8f553340337d9bca66702b4ce153a591f44ca805a24c1cbd65d413a1ee508f3adf5e0d8c9cb3dd80
+  data.tar.gz: 77001d5cad59b16980ab0e7adab15272de0ca1e993e6049f45afa300c70e904c68491d3041064fc74b49db8a5ce01f720dedc5f18ca70fdf6c2f5cc6751a269d

data/.editorconfig

@@ -7,6 +7,9 @@ indent_style = space
 insert_final_newline = true
 trim_trailing_whitespace = true
 
+[*.md]
+trim_trailing_whitespace = false
+
 [Makefile]
 indent_size = 4
 indent_style = tab

data/Makefile

@@ -0,0 +1,5 @@
+yard_server:
+	open http://localhost:8808
+	yard server --reload
+
+.PHONY: all

data/README.md

@@ -3,6 +3,7 @@
 [![Build Status](https://travis-ci.org/guzart/toktok.svg?branch=master)](https://travis-ci.org/guzart/toktok)
 [![codecov](https://codecov.io/gh/guzart/toktok/branch/master/graph/badge.svg)](https://codecov.io/gh/guzart/toktok)
 [![Code Climate](https://codeclimate.com/github/guzart/toktok/badges/gpa.svg)](https://codeclimate.com/github/guzart/toktok)
+[![Gem Version](https://badge.fury.io/rb/toktok.svg)](https://badge.fury.io/rb/toktok)
 
 
 JWT Authentication for Ruby
@@ -30,38 +31,49 @@ TODO: Improve
 **Configuration**
 
 ```ruby
+# 'none' | 'HS256' | 'RS256' | 'ES256'
 Toktok.algorithm = 'HS256'
-Toktok.secret_key = ENV['MY_SECRET_KEY']
+
+# REQUIRED unless algorithm = 'none'
+Toktok.secret_key = ENV['TOKTOK_SECRET_KEY'] 
+
+# OPTIONAL – in seconds
+Toktok.lifetime = nil 
 ```
 
 **Encode/Decode**
 
 ```ruby
-token = Toktok::Token.new(identity: 'guzart')
+token = Toktok::Token.new(identity: 'guzart', payload: { message: 'Hola' })
 puts token.jwt # 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1...'
 
 token = Toktok::Token.new(jwt: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1...')
 puts token.identity # 'guzart'
-puts token.payload # { sub: 'guzart' }
+puts token.payload # { sub: 'guzart', message: 'Hola' }
 ```
 
-## API
-
-TODO: list public api
+## Claims
 
-### ::Toktok
+### Subject Claim
 
-### ::Toktok::Token
+Toktok uses the required `identity` argument as the payload `sub` attribute defined
+by the [JWT Subject Claim](https://tools.ietf.org/html/rfc7519#section-4.1.2).
 
-## Claims
+### Expiration Time Claim
 
-TODO: describe relation in configuration and in token payload
+Toktok automatically calculates the token expiration using the `Toktok.lifetime` configuration
+value and sets the `exp` attribute defined by the
+[JWT Expiration Time Claim](https://tools.ietf.org/html/rfc7519#section-4.1.4)
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` 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).
+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
 

data/lib/toktok.rb

@@ -1,21 +1,44 @@
-require 'toktok/version'
-require 'jwt'
-
 module Toktok
   require 'toktok/configuration'
   require 'toktok/token'
+  require 'toktok/version'
 
+  # Set the algorithm used to encode and decode JWT tokens (default: HS256)
+  #
+  # Acceptable values are:
+  # * none
+  # * HS256, HS384, HS512
+  # * RS256, RS384, RS512
+  # * ES256, ES384, ES512
+  #
+  # @param [String] value the algorithm name
+  # @return [String] the algorithm
   def self.algorithm=(value)
     @algorithm = value
   end
 
+  # Set the lifetime in seconds before a token expires (default: nil)
+  #
+  # @param [Integer, nil] value the number of seconds before a token expires
+  # @return [Integer, nil] the lifetime
+  def self.lifetime=(value)
+    @lifetime = value
+  end
+
+  # Set the secret key that will be used to encode and decode JWT tokens
+  # @param [String] value the secret key
+  # @return [String] the secret key
   def self.secret_key=(value)
     @secret_key = value
   end
 
+  # Gets a Toktok::Configuration instance using the module values.
+  #
+  # @return [Toktok::Configuration] the configuration
   def self.config
     ::Toktok::Configuration.new(
       algorithm: @algorithm,
+      lifetime: @lifetime,
       secret_key: @secret_key
     )
   end

data/lib/toktok/configuration.rb

@@ -1,11 +1,13 @@
 module Toktok
   class Configuration
-    attr_reader :algorithm, :secret_key
+    attr_reader :algorithm, :lifetime, :secret_key
 
+    # Error raised when an algorithm is given but the secret_key is missing.
     SecretKeyMissingError = Class.new(StandardError)
 
-    def initialize(algorithm: nil, secret_key: nil)
+    def initialize(algorithm: nil, lifetime: nil, secret_key: nil)
       @algorithm = algorithm || 'HS256'
+      @lifetime = lifetime
       @secret_key = secret_key
 
       if algorithm != 'none' && (secret_key || '') == ''

data/lib/toktok/token.rb

@@ -1,27 +1,31 @@
+require 'jwt'
+
 module Toktok
   InvalidIdentity = Class.new(StandardError)
+  InvalidSignature = Class.new(StandardError)
 
   class Token
     attr_reader :config, :jwt, :payload
 
-    def initialize(identity: nil, jwt: nil)
+    def initialize(identity: nil, jwt: nil, payload: nil)
       @config = Toktok.config
       @payload = {}
       if jwt
         initialize_decode(jwt, identity)
       else
-        initialize_encode(identity)
+        initialize_encode(identity, payload)
       end
     end
 
     def identity
-      payload['sub']
+      payload[:sub]
     end
 
     private
 
-    def initialize_encode(identity)
-      @payload['sub'] = identity
+    def initialize_encode(identity, extra)
+      prepare_payload(identity, extra)
+      normalize_payload
       @jwt = JWT.encode(payload, config.secret_key, config.algorithm)
     end
 
@@ -29,10 +33,12 @@ module Toktok
       @jwt = jwt
       options = decode_options(identity)
       decoded_token = JWT.decode(jwt, config.secret_key, algorithm?, options)
-      @payload = decoded_token[0]
+      @payload = symbolize_keys(decoded_token[0])
       @header = decoded_token[1]
     rescue JWT::InvalidSubError
       raise InvalidIdentity, "Invalid identity. Expected #{identity}"
+    rescue JWT::VerificationError
+      raise InvalidSignature, 'Invalid or manipulated signature'
     end
 
     def decode_options(identity)
@@ -44,5 +50,20 @@ module Toktok
     def algorithm?
       config.algorithm != 'none'
     end
+
+    def prepare_payload(identity, extra = nil)
+      @payload.merge!(symbolize_keys(extra)) if extra
+      @payload[:sub] = identity
+      @payload[:exp] = Time.now.to_i + config.lifetime if config.lifetime.to_i > 0
+    end
+
+    # Guarantee the order in which the keys are inserted
+    def normalize_payload
+      @payload = Hash[payload.keys.sort.map { |k| [k, payload[k]] }]
+    end
+
+    def symbolize_keys(hash)
+      Hash[hash.map { |k, v| [k.to_sym, v] }]
+    end
   end
 end

data/lib/toktok/version.rb

@@ -1,3 +1,3 @@
 module Toktok
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/toktok.gemspec

@@ -34,4 +34,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'reek', '~> 4.5'
   spec.add_development_dependency 'rspec', '~> 3.5'
+  spec.add_development_dependency 'timecop', '~> 0.8'
+  spec.add_development_dependency 'yard', '~> 0.9'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toktok
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Arturo Guzman
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-03-15 00:00:00.000000000 Z
+date: 2017-03-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jwt
@@ -136,6 +136,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.5'
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 description: |
   Simplify JWT token encoding and decoding for Ruby. Use a configuration initializer to standardize the use
   of JWT encoding/decoding accross your library. Simplifies the use of JWT Claims.
@@ -154,6 +182,7 @@ files:
 - Gemfile
 - Guardfile
 - LICENSE.txt
+- Makefile
 - README.md
 - Rakefile
 - bin/console