jwt_sessions 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 143a1452f628f1d201801cc8b7b4855de56479fb
-  data.tar.gz: e648fe573c4239e2359d808b5fb93e58d253cf59
+  metadata.gz: da93c28c622a3bac51b8f30be0190b0a3c79dda7
+  data.tar.gz: 29da1c13c80f4b89572d8f1c3ebe07dd031f775b
 SHA512:
-  metadata.gz: d81c0bda06caebed8b38ca9649de98c3e5680859beb7059fd5f0534239f1aeb5b859c0e6f0582bb4585de44b7eef83136fa735d1ac2f7fa6107949e82dd777bb
-  data.tar.gz: 7e717dc3a0326c81239d1ce12937182bcc5f7d59df884f9eb4e7513f7a398b8c42984b97865e8bdc6f1a3efc75e8b8c96225b04ff76c64adf44f95508cdc57e7
+  metadata.gz: 4a21622dd516292d881f87a0b22f140b8dc7c17be838b200cfa7ccbcbb8a1a55a7e7bd075f3ea49982c06811a24fdda721f7625f3b821e4dfeff9583311942a2
+  data.tar.gz: b5897c5ef7e0a3be5db1dcc67df71fd0eb56f4a5f3ee5008782c881b006a34e139be045e6a30e7632f5231bf425c62de3b62b150a9e92895befa522802ef346b

data/README.md

@@ -1,6 +1,7 @@
 # jwt_sessions
 [![Gem Version](https://badge.fury.io/rb/jwt_sessions.svg)](https://badge.fury.io/rb/jwt_sessions)
 [![Maintainability](https://api.codeclimate.com/v1/badges/53de11b8334933b1c0ef/maintainability)](https://codeclimate.com/github/tuwukee/jwt_sessions/maintainability)
+[![Codacy Badge](https://api.codacy.com/project/badge/Grade/c86efdfca81448919ec3e1c1e48fc152)](https://www.codacy.com/app/tuwukee/jwt_sessions?utm_source=github.com&utm_medium=referral&utm_content=tuwukee/jwt_sessions&utm_campaign=Badge_Grade)
 [![Build Status](https://travis-ci.org/tuwukee/jwt_sessions.svg?branch=master)](https://travis-ci.org/tuwukee/jwt_sessions)
 
 XSS/CSRF safe JWT auth designed for SPA
@@ -77,9 +78,18 @@ Specify an encryption key for JSON Web Tokens in `config/initializers/jwt_sessio
 It's adviced to store the key itself within the app secrets.
 
 ```ruby
+JWTSessions.algorithm = 'HS256'
 JWTSessions.encryption_key = Rails.application.secrets.secret_jwt_encryption_key
 ```
 
+Most of the encryption algorithms require private and public keys to sign a token, yet HMAC only require a single key, so you can use a shortcat `encryotion_key` to sign the token. For other algorithms you must specify a private and public keys separately.
+
+```ruby
+JWTSessions.algorithm   = 'RS256'
+JWTSessions.private_key = OpenSSL::PKey::RSA.generate(2048)
+JWTSessions.public_key  = JWTSessions.private_key.public_key
+```
+
 Generate access/refresh/csrf tokens with a custom payload. \
 The payload will be available in the controllers once the access (or refresh) token is authorized. \
 Access/refresh tokens contain expiration time in their payload. Yet expiration times are also added to the output just in case.
@@ -290,9 +300,46 @@ JWTSessions.algorithm = 'HS256'
 You need to specify a secret to use for HMAC, this setting doesn't have a default value.
 
 ```ruby
-JWTSessions.secret = 'secret'
+JWTSessions.encryption_key = 'secret'
+```
+
+If you are using another algorithm like RSA/ECDSA/EDDSA you should specify private and public keys.
+
+```ruby
+JWTSessions.private_key = 'abcd'
+JWTSessions.public_key  = 'efjh'
+```
+
+NOTE: ED25519 and HS512256 require rbnacl installation in order to make it work.
+
+jwt_sessions only uses `exp` claim by default when it decodes tokens, you can specify which additional claims to use by
+setting `jwt_options`. You can also specify leeway to account for clock skew.
+
+```ruby
+JWTSessions.jwt_options.verify_iss = true
+JWTSessions.jwt_options.verify_sub = true
+JWTSessions.jwt_options.verify_iat = true
+JWTSessions.jwt_options.verify_aud = true
+JWTSessions.jwt_options.leeway     = 30 # seconds
 ```
 
+To pass options like `sub`, `aud`, `iss`, or leeways you should specify a method called `token_claims` in your controller.
+
+```ruby
+class UsersController < ApplicationController
+  before_action :authorize_access_request!
+
+  def token_claims
+    {
+      aud: ['admin', 'staff'],
+      exp_leeway: 15 # will be used instead of default leeway only for exp claim
+    }
+  end
+end
+```
+
+Claims are also supported by `JWTSessions::Session`, you can pass `access_claims` and `refresh_claims` options in the initializer
+
 ##### Request headers and cookies names
 
 Default request headers/cookies names can be re-configured
@@ -307,7 +354,7 @@ JWTSessions.csrf_header    = 'X-CSRF-Token'
 
 ##### Expiration time
 
-Acces token must have a short life span, while refresh tokens can be stored for a longer time period
+Access token must have a short life span, while refresh tokens can be stored for a longer time period
 
 ```ruby
 JWTSessions.access_exp_time = 3600 # 1 hour in seconds
@@ -341,17 +388,14 @@ session.refresh(refresh_token) { |refresh_token_uid, access_token_expiration| ..
 
 ## TODO
 
-Ability to specify public and private keys for RSA/EDCSA/EDDSA, there are no default values for keys. \
-You can use instructions from [ruby-jwt](https://github.com/jwt/ruby-jwt) to generate keys corresponding keys.
-
-```ruby
-JWTSessions.private_key = 'private_key'
-JWTSessions.public_key  = 'public_key_for_private'
-```
+Session cleanup by uid or refresh token instance. \
+Refresh token namespaces to allow centralized token cleanup per namespace (scenarios like password reset). \
+Documentation for code.
 
 ## Contributing
 
-Fork & Pull Request
+Fork & Pull Request \
+RbNaCl and sodium cryptographic library are required for tests
 
 ## License
 

data/lib/jwt_sessions/authorization.rb

@@ -14,7 +14,8 @@ module JWTSessions
         rescue Errors::Unauthorized
           cookie_based_auth(token_type)
         end
-        invalid_authorization unless Token.valid_payload?(payload)
+        # triggers token decode and jwt claim checks
+        payload
         check_csrf(token_type)
       end
     end
@@ -83,7 +84,8 @@ module JWTSessions
     end
 
     def payload
-      @_payload ||= Token.decode(found_token).first
+      claims = respond_to?(:token_claims) ? token_claims : {}
+      @_payload ||= Token.decode(found_token, claims).first
     end
   end
 end

data/lib/jwt_sessions/session.rb

@@ -9,6 +9,8 @@ module JWTSessions
       @store           = options.fetch(:store, JWTSessions.token_store)
       @refresh_payload = options.fetch(:refresh_payload, {})
       @payload         = options.fetch(:payload, {})
+      @access_claims   = options.fetch(:access_claims, {})
+      @refresh_claims  = options.fetch(:refresh_claims, {})
     end
 
     def login
@@ -60,17 +62,17 @@ module JWTSessions
     end
 
     def access_token_data(token)
-      uid = token_uid(token, :access)
+      uid = token_uid(token, :access, @access_claims)
       store.fetch_access(uid)
     end
 
     def refresh_token_data(token)
-      uid = token_uid(token, :refresh)
+      uid = token_uid(token, :refresh, @refresh_claims)
       retrieve_refresh_token(uid)
     end
 
-    def token_uid(token, type)
-      token_payload = JWTSessions::Token.decode(token).first
+    def token_uid(token, type, claims)
+      token_payload = JWTSessions::Token.decode(token, claims).first
       uid           = token_payload.fetch('uid', nil)
       if uid.nil?
         message = "#{type.to_s.capitalize} token payload does not contain token uid"

data/lib/jwt_sessions/token.rb

@@ -7,30 +7,21 @@ module JWTSessions
     class << self
       def encode(payload)
         exp_payload = meta.merge(payload)
-        JWT.encode(exp_payload, JWTSessions.encryption_key, JWTSessions.algorithm)
+        JWT.encode(exp_payload, JWTSessions.private_key, JWTSessions.algorithm)
       end
 
-      def decode(token)
-        JWT.decode(token, JWTSessions.encryption_key, true, { algorithm: JWTSessions.algorithm, verify_expiration: false })
+      def decode(token, claims = {})
+        decode_options = { algorithm: JWTSessions.algorithm }.merge(JWTSessions.jwt_options.to_h).merge(claims)
+        JWT.decode(token, JWTSessions.public_key, JWTSessions.validate?, decode_options)
       rescue JWT::DecodeError => e
         raise Errors::Unauthorized, e.message
       rescue StandardError
         raise Errors::Unauthorized, 'could not decode a token'
       end
 
-      def valid_payload?(payload)
-        !expired?(payload)
-      end
-
       def meta
         { exp: JWTSessions.access_expiration }
       end
-
-      def expired?(payload)
-        Time.at(payload['exp']) < Time.now
-      rescue StandardError
-        raise Errors::Unauthorized, 'invalid payload expiration time'
-      end
     end
   end
 end

data/lib/jwt_sessions/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JWTSessions
-  VERSION = '1.0.2'
+  VERSION = '1.1.0'
 end

data/lib/jwt_sessions.rb

@@ -18,6 +18,10 @@ module JWTSessions
 
   attr_writer :token_store
 
+  NONE = 'none'
+
+  JWTOptions = Struct.new(*JWT::DefaultOptions::DEFAULT_OPTIONS.keys)
+
   DEFAULT_SETTINGS_KEYS = %i[access_cookie
                              access_exp_time
                              access_header
@@ -30,19 +34,19 @@ module JWTSessions
                              refresh_exp_time
                              refresh_header
                              token_prefix].freeze
-  DEFAULT_REDIS_HOST = '127.0.0.1'
-  DEFAULT_REDIS_PORT = '6379'
-  DEFAULT_REDIS_DB_NAME = 'jwtokens'
-  DEFAULT_TOKEN_PREFIX = 'jwt_'
-  DEFAULT_ALGORITHM = 'HS256'
-  DEFAULT_ACCESS_EXP_TIME = 3600 # 1 hour in seconds
-  DEFAULT_REFRESH_EXP_TIME = 604800 # 1 week in seconds
-  DEFAULT_ACCESS_COOKIE = 'jwt_access'
-  DEFAULT_ACCESS_HEADER = 'Authorization'
-  DEFAULT_REFRESH_COOKIE = 'jwt_refresh'
-  DEFAULT_REFRESH_HEADER = 'X-Refresh-Token'
-  DEFAULT_CSRF_HEADER = 'X-CSRF-Token'
 
+  DEFAULT_REDIS_HOST       = '127.0.0.1'
+  DEFAULT_REDIS_PORT       = '6379'
+  DEFAULT_REDIS_DB_NAME    = 'jwtokens'
+  DEFAULT_TOKEN_PREFIX     = 'jwt_'
+  DEFAULT_ALGORITHM        = 'HS256'
+  DEFAULT_ACCESS_EXP_TIME  = 3600 # 1 hour in seconds
+  DEFAULT_REFRESH_EXP_TIME = 604800 # 1 week in seconds
+  DEFAULT_ACCESS_COOKIE    = 'jwt_access'
+  DEFAULT_ACCESS_HEADER    = 'Authorization'
+  DEFAULT_REFRESH_COOKIE   = 'jwt_refresh'
+  DEFAULT_REFRESH_HEADER   = 'X-Refresh-Token'
+  DEFAULT_CSRF_HEADER      = 'X-CSRF-Token'
 
   DEFAULT_SETTINGS_KEYS.each do |setting|
     var_name = :"@#{setting}"
@@ -61,13 +65,41 @@ module JWTSessions
     end
   end
 
+  def jwt_options
+    @jwt_options ||= JWTOptions.new(*JWT::DefaultOptions::DEFAULT_OPTIONS.values)
+  end
+
+  def algorithm=(algo)
+    raise Errors::Malconfigured, "algorithm #{algo} is not supported" unless supported_algos.include?(algo)
+    @algorithm = algo
+  end
+
   def token_store
     RedisTokenStore.instance(redis_host, redis_port, redis_db_name, token_prefix)
   end
 
-  def encryption_key
-    raise Errors::Malconfigured, 'encryption_key is not specified' unless @encryption_key
-    @encryption_key
+  def validate?
+    algorithm != NONE
+  end
+
+  [:public_key, :private_key].each do |key|
+    var_name = :"@#{key}"
+    define_method("#{key}") do
+      return nil if algorithm == NONE
+      var = instance_variable_get(var_name)
+      raise Errors::Malconfigured, "#{key} is not specified" unless var
+      var
+    end
+
+    define_method("#{key}=") do |val|
+      instance_variable_set(var_name, val)
+    end
+  end
+
+  # should be used for hmac only
+  def encryption_key=(key)
+    @public_key  = key
+    @private_key = key
   end
 
   def access_expiration
@@ -78,9 +110,6 @@ module JWTSessions
     Time.now.to_i + refresh_exp_time.to_i
   end
 
-  def encryption_key=(key)
-    @encryption_key = key
-  end
 
   def header_by(token_type)
     send("#{token_type}_header")
@@ -89,4 +118,12 @@ module JWTSessions
   def cookie_by(token_type)
     send("#{token_type}_cookie")
   end
+
+  private
+
+  def supported_algos
+    # TODO once ECDSA is fixed in ruby-jwt it can be added to the list of algos just the same way others are added
+    algos = JWT::Algos.constants - [:Unsupported, :Ecdsa]
+    algos.map { |algo| JWT::Algos.const_get(algo)::SUPPORTED }.flatten + [NONE, *JWT::Algos::Ecdsa::SUPPORTED.split(' ')]
+  end
 end

data/test/units/jwt_sessions/test_session.rb

@@ -39,10 +39,10 @@ class TestSession < Minitest::Test
     JWTSessions.access_exp_time = 0
     @session = JWTSessions::Session.new(payload: payload)
     @tokens = session.login
+    JWTSessions.access_exp_time = 3600
     refreshed_tokens = session.refresh(tokens[:refresh]) do
       raise JWTSessions::Errors::Unauthorized
     end
-    JWTSessions.access_exp_time = 3600
     decoded_access = JWTSessions::Token.decode(refreshed_tokens[:access]).first
     assert_equal EXPECTED_KEYS, refreshed_tokens.keys.sort
     assert_equal payload[:test], decoded_access['test']

data/test/units/jwt_sessions/test_token.rb

@@ -2,17 +2,128 @@
 
 require 'minitest/autorun'
 require 'jwt_sessions'
+require 'pry'
+
+nacl_supported_versions = {
+  'ruby'  => ['~> 2.2.6', '~> 2.3.0', '~> 2.4.2'],
+  'jruby' => ['~> 9.1.6.0']
+}.each_with_object([]) do |(platform, versions), acc|
+  acc.concat(versions.map { |version| Gem::Dependency.new(platform, version) })
+end
+
+nacl_supported = nacl_supported_versions.any? { |version| version.match?(RUBY_ENGINE, RUBY_VERSION) }
+
+$uses_nacl = !!(defined?(RbNaCl) || require('rbnacl') if nacl_supported)
 
 class TestToken < Minitest::Test
   attr_reader :payload
 
   def setup
-    JWTSessions.encryption_key = 'super secret'
     @payload = { 'user_id' => 1, 'secret' => 'mystery' }
+    JWTSessions.encryption_key = 'abcdefghijklmnopqrstuvwxyzABCDEF'
+  end
+
+  def teardown
+    JWTSessions.algorithm = JWTSessions::DEFAULT_ALGORITHM
+    JWTSessions.instance_variable_set(:'@jwt_options', JWTSessions::JWTOptions.new(*JWT::DefaultOptions::DEFAULT_OPTIONS.values))
+  end
+
+  def test_rsa_token_decode
+    JWTSessions.algorithm   = 'RS256'
+    JWTSessions.private_key = OpenSSL::PKey::RSA.generate 2048
+    JWTSessions.public_key  = JWTSessions.private_key.public_key
+
+    token   = JWTSessions::Token.encode(payload)
+    decoded = JWTSessions::Token.decode(token).first
+    assert_equal payload['user_id'], decoded['user_id']
+    assert_equal payload['secret'], decoded['secret']
+  end
+
+  def test_eddsa_token_decode
+    skip unless $uses_nacl
+    JWTSessions.algorithm   = 'ED25519'
+    JWTSessions.private_key = ::RbNaCl::Signatures::Ed25519::SigningKey.new('abcdefghijklmnopqrstuvwxyzABCDEF')
+    JWTSessions.public_key  = JWTSessions.private_key.verify_key
+
+    token   = JWTSessions::Token.encode(payload)
+    decoded = JWTSessions::Token.decode(token).first
+    assert_equal payload['user_id'], decoded['user_id']
+    assert_equal payload['secret'], decoded['secret']
+  end
+
+  def test_ecdsa_token_decode
+    JWTSessions.algorithm   = 'ES256'
+    JWTSessions.private_key = OpenSSL::PKey::EC.new 'prime256v1'
+    JWTSessions.private_key.generate_key
+    JWTSessions.public_key             = OpenSSL::PKey::EC.new JWTSessions.private_key
+    JWTSessions.public_key.private_key = nil
+
+    token   = JWTSessions::Token.encode(payload)
+    decoded = JWTSessions::Token.decode(token).first
+    assert_equal payload['user_id'], decoded['user_id']
+    assert_equal payload['secret'], decoded['secret']
+  end
+
+  def test_hmac_token_decode
+    JWTSessions.encryption_key = 'abcdefghijklmnopqrstuvwxyzABCDEF'
+    token   = JWTSessions::Token.encode(payload)
+    decoded = JWTSessions::Token.decode(token).first
+    assert_equal payload['user_id'], decoded['user_id']
+    assert_equal payload['secret'], decoded['secret']
+  end
+
+  def test_token_sub_claim
+    JWTSessions.encryption_key = 'abcdefghijklmnopqrstuvwxyzABCDEF'
+    JWTSessions.jwt_options.verify_sub = true
+    token   = JWTSessions::Token.encode(payload.merge(sub: 'subject'))
+    decoded = JWTSessions::Token.decode(token, { sub: 'subject' }).first
+    assert_equal payload['user_id'], decoded['user_id']
+    assert_equal payload['secret'], decoded['secret']
+    assert_raises JWTSessions::Errors::Unauthorized do
+      JWTSessions::Token.decode(token, { sub: 'different subject' })
+    end
+  end
+
+  def test_token_iss_claim
+    JWTSessions.encryption_key = 'abcdefghijklmnopqrstuvwxyzABCDEF'
+    JWTSessions.jwt_options.verify_iss = true
+    token   = JWTSessions::Token.encode(payload.merge(iss: 'Me'))
+    decoded = JWTSessions::Token.decode(token, { iss: 'Me' }).first
+    assert_equal payload['user_id'], decoded['user_id']
+    assert_equal payload['secret'], decoded['secret']
+    assert_raises JWTSessions::Errors::Unauthorized do
+      JWTSessions::Token.decode(token, { iss: 'Not Me' })
+    end
+  end
+
+  def test_token_aud_claim
+    JWTSessions.encryption_key = 'abcdefghijklmnopqrstuvwxyzABCDEF'
+    JWTSessions.jwt_options.verify_aud = true
+    token   = JWTSessions::Token.encode(payload.merge(aud: ['young', 'old']))
+    decoded = JWTSessions::Token.decode(token, { aud: ['young'] }).first
+    assert_equal payload['user_id'], decoded['user_id']
+    assert_equal payload['secret'], decoded['secret']
+    assert_raises JWTSessions::Errors::Unauthorized do
+      JWTSessions::Token.decode(token, { aud: ['adult'] })
+    end
+  end
+
+  def test_token_leeway_decode
+    JWTSessions.encryption_key = 'abcdefghijklmnopqrstuvwxyzABCDEF'
+    JWTSessions.jwt_options.leeway = 50
+    token   = JWTSessions::Token.encode(payload.merge(exp: Time.now.to_i - 20))
+    decoded = JWTSessions::Token.decode(token).first
+    assert_equal payload['user_id'], decoded['user_id']
+    assert_equal payload['secret'], decoded['secret']
+    token   = JWTSessions::Token.encode(payload.merge(exp: Time.now.to_i - 100))
+    assert_raises JWTSessions::Errors::Unauthorized do
+      JWTSessions::Token.decode(token)
+    end
   end
 
-  def test_valid_token_decode
-    token = JWTSessions::Token.encode(payload)
+  def test_none_token_decode
+    JWTSessions.algorithm = JWTSessions::NONE
+    token   = JWTSessions::Token.encode(payload)
     decoded = JWTSessions::Token.decode(token).first
     assert_equal payload['user_id'], decoded['user_id']
     assert_equal payload['secret'], decoded['secret']
@@ -31,12 +142,9 @@ class TestToken < Minitest::Test
   end
 
   def test_payload_exp_time
+    token = JWTSessions::Token.encode(payload.merge(exp: Time.now.to_i - (3600 * 24)))
     assert_raises JWTSessions::Errors::Unauthorized do
-      JWTSessions::Token.valid_payload?(payload)
+      JWTSessions::Token.decode(token)
     end
-    payload['exp'] = Time.now - (3600 * 24)
-    assert_equal false, JWTSessions::Token.valid_payload?(payload)
-    payload['exp'] = Time.now + (3600 * 24)
-    assert_equal true, JWTSessions::Token.valid_payload?(payload)
   end
 end

data/test/units/test_jwt_sessions.rb

@@ -21,7 +21,11 @@ class TestJWTSessions < Minitest::Test
   def test_encryption_key
     JWTSessions.encryption_key = nil
     assert_raises JWTSessions::Errors::Malconfigured do
-      JWTSessions.encryption_key
+      JWTSessions.private_key
+    end
+
+    assert_raises JWTSessions::Errors::Malconfigured do
+      JWTSessions.public_key
     end
   end
 

metadata

@@ -1,29 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: jwt_sessions
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.0
 platform: ruby
 authors:
 - Yulia Oletskaya
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-04-19 00:00:00.000000000 Z
+date: 2018-04-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jwt
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '2.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '2.1'
 - !ruby/object:Gem::Dependency
   name: redis
   requirement: !ruby/object:Gem::Requirement
@@ -86,14 +86,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '12.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '12.3'
 description: XSS/CSRF safe JWT auth designed for SPA
 email: yulia.oletskaya@gmail.com
 executables: []