jwt_keeper 2.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bd966e0e79df17e42e2f825289387dcb9f386bde
+  data.tar.gz: 32aaa2f138fd3102ea431b3b244fc77e6736bf3a
+SHA512:
+  metadata.gz: 842033c9c72f8c350a22c84075d78a8609beb43109bbfa10cb52eaea72034baa99609c862f2a6dc4d6866203c9ef15bfcabd091ef809d4b748fa5ee3519ee6b9
+  data.tar.gz: fca8a945722eace48870831e435e6628bd48a666dd7ced51d5066d0bee138b1837b9b838aded1b947464db5d4c73ddd9fa4211b7f39f97f022ae199551d3cde6

data/.editorconfig

@@ -0,0 +1,14 @@
+# EditorConfig is awesome: http://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+
+[*.rb]
+indent_style = space
+indent_size = 2

data/.gitignore

@@ -0,0 +1,21 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+vendor
+.ruby-version
+.env
+/spec/examples.txt

data/.rspec

@@ -0,0 +1,3 @@
+--format Fuubar
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,22 @@
+# inherit_from: .rubocop_todo.yml
+AllCops:
+  Include:
+    - 'Gemfile'
+    - 'Rakefile'
+    - '**/*.rake'
+Documentation:
+  Enabled: false
+Metrics/LineLength:
+  Max: 100
+Style/PercentLiteralDelimiters:
+  PreferredDelimiters:
+    '%':  ()
+    '%q': ()
+    '%Q': ()
+    '%i': []
+    '%I': []
+    '%r': ()
+    '%s': ()
+    '%w': []
+    '%W': []
+    '%x': ()

data/.travis.yml

@@ -0,0 +1,20 @@
+language: ruby
+rvm:
+  - 2.0.0
+  - 2.1.8
+  - 2.2.4
+  - 2.3.0
+  - ruby-head
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+addons:
+  code_climate:
+    repo_token: f69bb189f348c1d7992d8ed8690d0a2c9c885c1aac45e2f4d48732034592b37b
+services:
+  - redis-server
+env:
+  global:
+    - REDIS_URL=redis://localhost:6379
+notifications:
+  email: false

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,23 @@
+
+Copyright (c) 2014 David Rivera
+
+MIT License
+
+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,83 @@
+# JWT Keeper
+[![Build Status](https://img.shields.io/travis/sirwolfgang/jwt_keeper/master.svg)](https://travis-ci.org/sirwolfgang/jwt_keeper)
+[![Dependency Status](https://img.shields.io/gemnasium/sirwolfgang/jwt_keeper.svg)](https://gemnasium.com/sirwolfgang/jwt_keeper)
+[![Code Climate](https://img.shields.io/codeclimate/github/sirwolfgang/jwt_keeper.svg)](https://codeclimate.com/github/sirwolfgang/jwt_keeper)
+[![Test Coverage](https://img.shields.io/codeclimate/coverage/github/sirwolfgang/jwt_keeper.svg)](https://codeclimate.com/github/sirwolfgang/jwt_keeper/coverage)
+[![Inline docs](http://inch-ci.org/github/sirwolfgang/jwt_keeper.svg?style=shields)](http://inch-ci.org/github/sirwolfgang/jwt_keeper)
+
+An managing interface layer for handling the creation and validation of JWTs.
+
+## Setup
+ - Add `gem 'jwt_keeper', '~> 2.0'` to Gemfile
+ - Run `rails generate keeper:install`
+ - Configure `config/initializers/keeper.rb`
+ - Done
+
+## Basic Usage
+Here are the basic methods you can call to perform various operations
+
+```ruby
+token = JWTKeeper::Token.create(private_claim_hash)
+token = JWTKeeper::Token.find(raw_token_string)
+
+token.revoke
+token.rotate
+
+token.valid?
+raw_token_string = token.to_jwt
+```
+
+## Rails Usage
+The designed rails token flow is to receive and respond to requests with the token being present in the `Authorization` part of the header. This is to allow us to seamlessly rotate the tokens on the fly without having to rebuff the request as part of the user flow. Automatic rotation happens as part of the `require_authentication` action, meaning that you will always get the latest token data as
+created by `generate_claims` in your controllers. This new token is added to the response with
+the `respond_with_authentication` action.
+
+```ruby
+class ApplicationController < ActionController::Base
+  before_action :require_authentication
+  after_action :respond_with_authentication
+
+  def not_authenticated
+    # Overload to return status 401
+  end
+
+  def authenticated(token)
+    # Overload to make use of token data
+  end
+
+  def regenerate_claims(old_token)
+    # Overload to update claims on automatic rotation.
+    current_user = User.find(authentication_token.claims[:uid])
+    { uid: current_user.id, usn: current_user.email }
+  end
+end
+```
+
+```ruby
+class SessionsController < ApplicationController
+  skip_before_action :require_authentication, only: :create
+  skip_after_action :respond_with_authentication, only: :destroy
+
+  # POST /sessions
+  def create
+    authentication_token = JWTKeeper::Token.create({ uid: @user.id, usn: @user.email })
+  end
+
+  # PATCH/PUT /sessions
+  def update
+    authentication_token = request_token.rotate(generate_claims)
+  end
+
+  # DELETE /sessions
+  def destroy
+    request_token.revoke
+    authentication_token = nil
+  end
+```
+
+## Invalidation
+### Hard Invalidation
+Hard Invalidation is a permanent revocation of the token. The primary cases of this is when a user wishes to logout, or when your security has been otherwise compromised. To revoke all tokens simply update the configuration `secret`. To revoke a single token you can utilize either the class(`Token.revoke(jti)`) or instance(`token.revoke`) method.
+
+### Soft Invalidation
+Soft Invalidation is the process of triggering a rotation upon the next time a token is seen in a request. On the global scale this is done when there is a version mismatch in the config. Utilizing the rails controller flow, this method works even if you have two different versions of your app deployed and requests bounce back and forth; Making rolling deployments and rollbacks completely seamless. To rotate a single token, like in the case of a change of user permissions, simply use the class(`Token.rotate`) method to flag the token for regeneration.

data/Rakefile

@@ -0,0 +1,7 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new
+
+task default: :spec
+task test: :spec

data/docker-compose.yml

@@ -0,0 +1,4 @@
+redis:
+  image: redis:latest
+  ports:
+    - "6379:6379"

data/example.env

@@ -0,0 +1 @@
+REDIS_URL=redis://localhost:6379

data/jwt_keeper.gemspec

@@ -0,0 +1,36 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'jwt_keeper/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'jwt_keeper'
+  spec.version       = JWTKeeper::VERSION
+  spec.authors       = ['David Rivera', 'Zane Wolfgang Pickett']
+  spec.email         = ['david.r.rivera193@gmail.com', 'sirwolfgang@users.noreply.github.com']
+  spec.summary       = 'JWT for Rails made easy'
+  spec.description   = 'It is a keeper'
+  spec.homepage      = 'https://github.com/sirwolfgang/jwt_keeper'
+  spec.license       = 'MIT'
+
+  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_development_dependency 'bundler'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'yard'
+  spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'dotenv'
+
+  spec.add_development_dependency 'rspec', '~> 3.4'
+  spec.add_development_dependency 'fuubar'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'codeclimate-test-reporter'
+
+  spec.add_dependency 'redis', '~> 3.3'
+  spec.add_dependency 'rails', '~> 4.2'
+  spec.add_dependency 'activesupport', '~> 4.2'
+  spec.add_dependency 'jwt', '~> 1.5'
+end

data/lib/generators/keeper/install/install_generator.rb

@@ -0,0 +1,15 @@
+require 'rails/generators/base'
+
+module JWTKeeper
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path('../../../templates', __FILE__)
+
+    # Copies the default config
+    #
+    # @example Install
+    #   rails generate keeper:install
+    def copy_files
+      copy_file 'jwt_keeper.rb', 'config/initializers/keeper.rb'
+    end
+  end
+end

data/lib/generators/templates/jwt_keeper.rb

@@ -0,0 +1,32 @@
+JWTKeeper.configure do |config|
+  # The time to expire for the tokens
+  # config.expiry           = 24.hours
+
+  # The hashing method to for the tokens
+  # Options:
+  #   HS256 - HMAC using SHA-256 hash algorithm (default)
+  #   HS384 - HMAC using SHA-384 hash algorithm
+  #   HS512 - HMAC using SHA-512 hash algorithm
+  #   RS256 - RSA using SHA-256 hash algorithm
+  #   RS384 - RSA using SHA-384 hash algorithm
+  #   RS512 - RSA using SHA-512 hash algorithm
+  #   ES256 - ECDSA using P-256 and SHA-256
+  #   ES384 - ECDSA using P-384 and SHA-384
+  #   ES512 - ECDSA using P-521 and SHA-512
+  # config.algorithm        = 'HS512'
+
+  # the secret in which you data is hash with
+  # config.secret           = 'secret'
+
+  # the issuer of the tokens
+  # config.issuer           = 'api.example.com'
+
+  # the default audience of the tokens
+  # config.audience         = 'example.com'
+
+  # the location of redis config file
+  # config.redis_connection = Redis.new(connection_options)
+
+  # A unique idenfitier for the token version.
+  # config.version = 1
+end

data/lib/jwt_keeper/configuration.rb

@@ -0,0 +1,30 @@
+module JWTKeeper
+  class Configuration < OpenStruct
+    DEFAULTS = {
+      algorithm:       'HS512',
+      secret:           nil,
+      expiry:           24.hours,
+      issuer:           'api.example.com',
+      audience:         'example.com',
+      redis_connection: nil,
+      version:          nil
+    }.freeze
+
+    # Creates a new Configuration from the passed in parameters
+    # @param params [Hash] configuration options
+    # @return [Configuration]
+    def initialize(params = {})
+      super(DEFAULTS.merge(params))
+    end
+
+    # @!visibility private
+    def base_claims
+      {
+        iss: JWTKeeper.configuration.issuer,               # issuer
+        aud: JWTKeeper.configuration.audience,             # audience
+        exp: JWTKeeper.configuration.expiry.from_now.to_i, # expiration time
+        ver: JWTKeeper.configuration.version               # Version
+      }
+    end
+  end
+end

data/lib/jwt_keeper/controller.rb

@@ -0,0 +1,66 @@
+module JWTKeeper
+  module Controller
+    def self.included(klass)
+      klass.class_eval do
+        include InstanceMethods
+      end
+    end
+
+    module InstanceMethods
+      # Available to be used as a before_action by the application's controllers. This is
+      # the main logical section for decoding, and automatically rotating tokens
+      def require_authentication
+        token = authentication_token
+        return not_authenticated if token.nil?
+
+        if token.version_mismatch? || token.pending?
+          new_claims = regenerate_claims(token)
+          token.rotate(new_claims)
+          self.authentication_token = token
+        end
+
+        authenticated(token)
+      end
+
+      # Invoked by the require_authentication method as part of the automatic rotation
+      # process. The application should override this method to include the necessary
+      # claims.
+      def regenerate_claims(old_token)
+      end
+
+      # Moves the authentication_token from the request to the response
+      def respond_with_authentication
+        response.headers['Authorization'] = request.headers['Authorization']
+      end
+
+      # Decodes and returns the token
+      def authentication_token
+        return nil unless request.headers['Authorization']
+        JWTKeeper::Token.find(request.headers['Authorization'].split.last)
+      end
+
+      # Assigns a token to the request to act as a single source of truth
+      def authentication_token=(token)
+        request.headers['Authorization'] = "Bearer #{token.to_jwt}"
+      end
+
+      # Used when a user tries to access a page while logged out, is asked to login,
+      # and we want to return him back to the page he originally wanted.
+      def redirect_back_or_to(url, flash_hash = {})
+        redirect_to(session[:return_to_url] || url, flash: flash_hash)
+        session[:return_to_url] = nil
+      end
+
+      # The default action for denying non-authenticated connections.
+      # You can override this method in your controllers
+      def not_authenticated
+        redirect_to root_path
+      end
+
+      # The default action for accepting authenticated connections.
+      # You can override this method in your controllers
+      def authenticated(token)
+      end
+    end
+  end
+end

data/lib/jwt_keeper/datastore.rb

@@ -0,0 +1,39 @@
+module JWTKeeper
+  module Datastore
+    class << self
+      # @!visibility private
+      def rotate(jti, seconds)
+        set_with_expiry(jti, seconds, :soft)
+      end
+
+      # @!visibility private
+      def revoke(jti, seconds)
+        set_with_expiry(jti, seconds, :hard)
+      end
+
+      # @!visibility private
+      def pending?(jti)
+        value = get(jti)
+        value.present? && value.to_sym == :soft
+      end
+
+      # @!visibility private
+      def revoked?(jti)
+        value = get(jti)
+        value.present? && value.to_sym == :hard
+      end
+
+      private
+
+      # @!visibility private
+      def set_with_expiry(jti, seconds, type)
+        JWTKeeper.configuration.redis_connection.setex(jti, seconds, type)
+      end
+
+      # @!visibility private
+      def get(jti)
+        JWTKeeper.configuration.redis_connection.get(jti)
+      end
+    end
+  end
+end

data/lib/jwt_keeper/engine.rb

@@ -0,0 +1,12 @@
+require 'jwt_keeper'
+require 'rails'
+
+module JWTKeeper
+  # The Sorcery engine takes care of extending ActiveRecord (if used) and ActionController,
+  # With the plugin logic.
+  class Engine < ::Rails::Engine
+    initializer 'extend Controller with keeper' do |_app|
+      ActionController::Base.send(:include, JWTKeeper::Controller)
+    end
+  end
+end

data/lib/jwt_keeper/exceptions.rb

@@ -0,0 +1,19 @@
+module JWTKeeper
+  # The token is invalid
+  class InvalidTokenError < StandardError; end
+
+  # The token expiry claim is invalid
+  class ExpiredTokenError < InvalidTokenError; end
+
+  # The token was force expired
+  class RevokedTokenError < InvalidTokenError; end
+
+  # The token not before claim is invalid
+  class EarlyTokenError < InvalidTokenError; end
+
+  # The token issuer claim is invalid
+  class BadIssuerError < InvalidTokenError; end
+
+  # The token audience claim is invalid
+  class LousyAudienceError < InvalidTokenError; end
+end

data/lib/jwt_keeper/token.rb

@@ -0,0 +1,137 @@
+module JWTKeeper
+  class Token
+    attr_accessor :claims
+
+    # Initalizes a new web token
+    # @param private_claims [Hash] the custom claims to encode
+    def initialize(private_claims = {})
+      @claims = {
+        nbf: DateTime.now.to_i, # not before
+        iat: DateTime.now.to_i, # issued at
+        jti: SecureRandom.uuid  # JWT ID
+      }
+      @claims.merge!(JWTKeeper.configuration.base_claims)
+      @claims.merge!(private_claims)
+    end
+
+    # Creates a new web token
+    # @param private_claims [Hash] the custom claims to encode
+    # @return [Token] token object
+    def self.create(private_claims)
+      new(private_claims)
+    end
+
+    # Decodes and validates an existing token
+    # @param raw_token [String] the raw token
+    # @return [Token] token object
+    def self.find(raw_token)
+      claims = decode(raw_token)
+      return nil if claims.nil?
+
+      new_token = new(claims)
+      return nil if new_token.revoked?
+      new_token
+    end
+
+    # Sets a token to the pending rotation state. The expire is set to the maxium possible time but
+    # is inherently ignored by the token's exp check and then rewritten with the revokation on
+    # rotate.
+    # @param token_jti [String] the token unique id
+    def self.rotate(token_jti)
+      Datastore.rotate(token_jti, JWTKeeper.configuration.expiry.from_now.to_i)
+    end
+
+    # Revokes a web token
+    # @param token_jti [String] the token unique id
+    def self.revoke(token_jti)
+      Datastore.revoke(token_jti, JWTKeeper.configuration.expiry.from_now.to_i)
+    end
+
+    # Easy interface for using the token's id
+    # @return [String] token's uuid
+    def id
+      claims[:jti]
+    end
+
+    # Revokes and creates a new web token
+    # @param new_claims [Hash] Used to override and update claims during rotation
+    # @return [String] new token
+    def rotate(new_claims = nil)
+      revoke
+
+      new_claims ||= claims.except(:iss, :aud, :exp, :nbf, :iat, :jti)
+      new_token = self.class.new(new_claims)
+      @claims = new_token.claims
+      self
+    end
+
+    # Revokes a web token
+    def revoke
+      return if invalid?
+      Datastore.revoke(id, claims[:exp] - DateTime.now.to_i)
+    end
+
+    # Checks if a web token is pending a rotation
+    # @return [Boolean]
+    def pending?
+      Datastore.pending?(id)
+    end
+
+    # Checks if a web token is pending a global rotation
+    # @return [Boolean]
+    def version_mismatch?
+      claims[:ver] != JWTKeeper.configuration.version
+    end
+
+    # Checks if a web token has been revoked
+    # @return [Boolean]
+    def revoked?
+      Datastore.revoked?(id)
+    end
+
+    # Checks if the token valid?
+    # @return [Boolean]
+    def valid?
+      !invalid?
+    end
+
+    # Checks if the token invalid?
+    # @return [Boolean]
+    def invalid?
+      self.class.decode(encode).nil? || revoked?
+    end
+
+    # Encodes the jwt
+    # @return [String]
+    def to_jwt
+      encode
+    end
+    alias to_s to_jwt
+
+    # @!visibility private
+    def self.decode(raw_token)
+      JWT.decode(raw_token, JWTKeeper.configuration.secret, true,
+                 algorithm: JWTKeeper.configuration.algorithm,
+                 verify_iss: true,
+                 verify_aud: true,
+                 verify_iat: true,
+                 verify_sub: false,
+                 verify_jti: false,
+                 leeway: 0,
+
+                 iss: JWTKeeper.configuration.issuer,
+                 aud: JWTKeeper.configuration.audience
+                ).first.symbolize_keys
+
+    rescue JWT::DecodeError
+      return nil
+    end
+
+    private
+
+    # @!visibility private
+    def encode
+      JWT.encode(claims, JWTKeeper.configuration.secret, JWTKeeper.configuration.algorithm)
+    end
+  end
+end

data/lib/jwt_keeper/version.rb

@@ -0,0 +1,4 @@
+# Gem Version
+module JWTKeeper
+  VERSION = '2.0.0'.freeze
+end

data/lib/jwt_keeper.rb

@@ -0,0 +1,28 @@
+require 'jwt'
+require 'redis'
+require 'active_support'
+require 'active_support/core_ext/numeric'
+
+require 'jwt_keeper/version'
+require 'jwt_keeper/exceptions'
+require 'jwt_keeper/configuration'
+require 'jwt_keeper/datastore'
+require 'jwt_keeper/token'
+require 'jwt_keeper/controller'
+
+module JWTKeeper
+  class << self
+    attr_reader :configuration, :datastore
+  end
+
+  # Creates/sets a new configuration for the gem, yield a configuration object
+  # @param new_configuration [Configuration] new configuration
+  # @return [Configuration] the frozen configuration
+  def self.configure(new_configuration = Configuration.new)
+    yield(new_configuration) if block_given?
+
+    @configuration = new_configuration.freeze
+  end
+
+  require 'jwt_keeper/engine' if defined?(Rails)
+end

data/spec/lib/keeper/configuration_spec.rb

@@ -0,0 +1,5 @@
+require 'spec_helper'
+
+RSpec.describe JWTKeeper::Configuration do
+  it { expect have_constant('DEFAULTS') }
+end