henlo 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 51d705728f88bb4c77b243d887d05f729d2a2019
+  data.tar.gz: 968ea1f50cecc17d754fe04617e117a02e6d9c88
+SHA512:
+  metadata.gz: e30c6ffaf47154ffe110b3218d7a4ad7f972ddc1a4d5b6b27940342cd23dd7a98d0bc8ae96fa6a1476d0c215ecbd149a0588662609e4bd41715f4a27de96b6d4
+  data.tar.gz: 19986364a62c80e02052f7cdbbbc98043a54ba37351afff6d616275cfa69d53fb05641c92226db268f1bc513527c559466236123d7079d940cccaa41a4aa9dc5

data/Rakefile

@@ -0,0 +1,15 @@
+require "rubygems"
+
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+
+Bundler::GemHelper.install_tasks
+
+task default: :test

data/lib/generators/henlo/install_generator.rb

@@ -0,0 +1,17 @@
+require 'rails/generators/base'
+
+module Henlo
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../templates", __FILE__)
+      desc "Installs Henlo."
+
+      def copy_initializer
+        template "henlo_initializer.rb", "config/initializers/henlo.rb"
+
+        puts "Installation complete."
+      end
+      
+    end
+  end
+end

data/lib/generators/henlo/migrations_generator.rb

@@ -0,0 +1,33 @@
+require 'rails/generators/active_record'
+
+module Henlo
+  module Generators
+    class MigrationsGenerator < ActiveRecord::Generators::Base
+      source_root File.expand_path("../../templates", __FILE__)
+      desc "Generates the necessary migration for the model"
+      argument :table_name, type: :string, default: "User"
+
+
+      def create_migrations
+        puts "Generating migrations for model #{table_name}.downcase"
+        migration_template "migrations/add_jti_column.rb", "db/migrate/add_jti_column_to_#{table_name.downcase.pluralize}.rb"
+        migration_template 'migrations/create_blacklisted_tokens.rb.erb', 'db/migrate/create_blacklisted_tokens.rb'
+      end
+
+      def migration_data
+<<RUBY
+      t.string :refresh_token_jti 
+      t.boolean :blacklist_check, default: false 
+RUBY
+      end
+      
+      def migration_index_data 
+<<RUBY
+      add_index "#{table_name.downcase.pluralize.to_sym}", :blacklist_check
+      add_index "#{table_name.downcase.pluralize.to_sym}", :refresh_token_jti 
+RUBY
+      end 
+
+    end
+  end
+end

data/lib/generators/templates/henlo_initializer.rb

@@ -0,0 +1,23 @@
+Henlo.setup do |config|
+
+  ## All expiration claims use seconds as unit
+
+  ## Refresh token expiration claim
+  ## ----------------
+  ##
+  ## How long before a refresh token is expired. If nil is provided, token will
+  ## last forever.
+  ##
+  ## Default is 15 days
+  # config.refresh_token_lifetime = 15 * 86400
+
+  ## Id token expiration claim
+  ## ----------------
+  ##
+  ## How long before an id token is expired. If nil is provided, token will
+  ## last forever.
+  ## This value is provided in seconds
+  ## Default is 15 minutes
+  # config.id_token_lifetime = 60 * 15
+  
+end

data/lib/generators/templates/migrations/add_jti_column.rb

@@ -0,0 +1,16 @@
+  <%
+  parent_class = ActiveRecord::Migration
+  parent_class = parent_class[parent_class.current_version] if Rails::VERSION::MAJOR >= 5
+-%>
+class AddJtiColumnTo<%= table_name.camelize %>s < <%= parent_class.to_s %>
+  def self.up
+    change_table(:<%= table_name.downcase.pluralize %>) do |t|
+<%= migration_data %>
+    end
+<%= migration_index_data%>
+  end
+
+  def self.down
+    raise ActiveRecord::IrreversibleMigration
+  end
+end

data/lib/generators/templates/migrations/create_blacklisted_tokens.rb.erb

@@ -0,0 +1,21 @@
+<%
+  parent_class = ActiveRecord::Migration
+  parent_class = parent_class[parent_class.current_version] if Rails::VERSION::MAJOR >= 5
+-%>
+class CreateBlacklistedTokens < <%= parent_class.to_s %>
+  def self.up
+    create_table :blacklisted_tokens do |t|
+      t.string :token_jti
+      <%- if Rails::VERSION::MAJOR >= 5 -%>
+      t.integer :exp_in_unix
+      t.timestamps
+      <%- else -%>
+      t.timestamps null: false
+      <%- end -%>
+    end
+  end
+
+  def self.down
+    drop_table :blacklisted_tokens
+  end
+end

data/lib/henlo.rb

@@ -0,0 +1,46 @@
+require "henlo/version"
+require "henlo/refreshable"
+require "henlo/identifiable"
+require "henlo/authenticable"
+require "henlo/revocable"
+require "knock"
+
+#
+## Defines default initializing values and main method for generating tokens 
+module Henlo
+  
+  #
+  ## Generates refresh and access tokens when method is called, allows the passing in of 
+  ## additional key value pairs to be encoded in the jwt payload
+  ## Returns the jwt identifier of the refresh token, as well as the expiry time in unix
+  ## seconds of the id token.
+  def self.generate_henlos(options={})
+    claim = options || nil 
+    refresh_token_and_jti = Refreshable.generate_refreshable(options) 
+    id_token_and_exp = Identifiable.generate_identifiable(options)
+    tokens = Hash[
+      id_token: id_token_and_exp[:token],
+      refresh_token: refresh_token_and_jti[:token]
+    ]
+    henlos = Hash[
+      tokens: tokens, 
+      jti: refresh_token_and_jti[:jti],
+      exp: id_token_and_exp[:exp]
+    ]
+  end
+
+  mattr_accessor :refresh_token_lifetime
+  self.refresh_token_lifetime = 15 * 86400
+   
+  mattr_accessor :id_token_lifetime
+  self.id_token_lifetime = 60 * 15
+
+  #  Default way to setup Henlo. Run `rails generate henlo:install` to create
+  ## a fresh initializer with all configuration values.
+  def self.setup
+    yield self
+  end
+
+
+end
+

data/lib/henlo/authenticable.rb

@@ -0,0 +1,90 @@
+require "henlo/helpers/util"
+require 'active_record/errors'
+#
+## Module
+module Henlo::Authenticable
+  
+  #
+  ## Retrieve the token type from the jwt payload 
+  def self.parse_token_type(token, options={})
+    claim = Knock::AuthToken.new(token: token, verify_options: options).payload
+    claim["type"]
+  end 
+  
+  #
+  ## Match the token jwt identifier with what is stored in the database for the resource,
+  ## a lack of match indicates suspicious activities
+  def self.jti_match?(payload, resource)
+    payload["jti"] === resource.refresh_token_jti
+  end 
+  
+  #
+  ## Check the resource to see if it has been flagged for blacklist check 
+  def self.it_suspicious?(resource)
+    resource.blacklist_check?    
+  end 
+
+  #
+  ## Check the blacklisted tokens table to see whether the token's jwt identifier has been
+  ## blacklisted
+  def self.it_not_fren?(resource)
+    BlacklistedToken.where(token_jti: resource.refresh_token_jti).first
+  end 
+  
+  #
+  ## Parse the resource as identified by the id encoded in the jwt with the key "sub" 
+  def self.parse_resource(payload, model)
+    resource = model.capitalize.constantize.where(id: payload["sub"]).first
+    if resource.nil? 
+      raise ActiveRecord::RecordNotFound
+    end
+    resource
+  end 
+  
+  #
+  ## Authenticates resource by first determining the treatment based on the type of token. 
+  ## Requests with valid id tokens will be processed. 
+  ## Requests with refresh tokens will be checked for 1) whether the resource has been flagged
+  ## for blacklist check and if yes, 2) whether the token's jwt identifier has been flaglisted.
+  ## If neither 1) nor 2) is established, the token will be checked for a match of the jwt identifier
+  ## The resource is returned if all these checks are passed.
+  def self.it_me?(token, model)
+    type = parse_token_type(token)
+    payload = Knock::AuthToken.new(token: token).payload
+    resource = parse_resource(payload, model)
+    case type 
+    when "id"
+      resource
+    when "refresh"
+      if it_suspicious?(resource) && it_not_fren?(resource)
+        nil
+      else 
+        if jti_match?(payload, resource)
+          resource
+        else 
+          Henlo::Revocable.token_blockt(payload, resource)
+          nil 
+        end       
+      end 
+    else 
+      nil 
+    end 
+  end 
+  
+  #
+  ## This method is to be called before `it_me?` is called, so that expired tokens are treated before
+  ## the authentication begins. Requests made with expired id tokens are rejected with an error. 
+  ## Requests made with expired refresh tokens are then processed with "reauthentication_strategy. 
+  ## This method is passed as an argument to `it_expired` by the app. You can define how 
+  ## users are reauthenticated in your own app.  
+  def self.it_expired(reauthenticate_strategy, token, model)
+    token = Knock::AuthToken.new(token: token, verify_options: {verify_expiration: false}).token
+    claim = Knock::AuthToken.new(token: token, verify_options: {verify_expiration: false}).payload
+    resource = parse_resource(claim, model)
+    if claim["type"] == "id"
+      raise ActionController::InvalidAuthenticityToken 
+    else 
+      reauthenticate_strategy
+    end    
+  end 
+end 

data/lib/henlo/helpers/util.rb

@@ -0,0 +1,17 @@
+
+#
+## Helper methods 
+module Henlo 
+  module Helpers 
+    module Util 
+      
+      #
+      ## Generates a random string in the format of "a5391f26-1136-46f3-a3d3-ea4e1e558f06"
+      ## to use as a unique jwt identifier. 
+      def self.generate_jti 
+        SecureRandom.uuid
+      end 
+
+    end 
+  end 
+end 

data/lib/henlo/identifiable.rb

@@ -0,0 +1,26 @@
+require "henlo/helpers/util"
+
+#
+## Generates id token. The id token is used to identify and authenticate the user before 
+## responding to a request
+module Henlo::Identifiable
+  
+  # Generates id token and returns both the token, with the optional payload encoded, and the
+  ## token expiry time in unix seconds
+  def self.generate_identifiable(options={})
+    claim = options || nil 
+   
+    claim.merge!({
+      exp: Time.now.utc.to_i + Henlo.id_token_lifetime, 
+      jti: Henlo::Helpers::Util.generate_jti,
+      type: "id"
+    })
+
+    Hash[
+      token: Knock::AuthToken.new(payload: claim).token, 
+      exp: claim[:exp]       
+    ]
+  end 
+ 
+
+end 

data/lib/henlo/refreshable.rb

@@ -0,0 +1,33 @@
+require "henlo/helpers/util"
+
+#
+## Module for generating refresh tokens
+
+module Henlo::Refreshable
+  
+  #
+  ## Generate refreshable token with a unix time for expiry, the type of token 
+  ## and the jwt identifier (a random string) encoded in the payload in addition to 
+  ## whatever was passed as payload when `generate_henlos` was called
+  def self.generate_refreshable(options={})
+    claim = options || nil 
+    
+    claim.merge!({
+      exp: Time.now.utc.to_i + Henlo.refresh_token_lifetime, 
+      jti: Henlo::Helpers::Util.generate_jti,
+      type: "refresh"
+    })
+    
+    Hash[
+      token: Knock::AuthToken.new(payload: claim).token, 
+      jti: claim[:jti]       
+    ]
+  end 
+
+  #
+  ## Store jwt identifier in the app's database, in the table of the resource  
+  def self.store_jti(resource, jti)
+    resource.update_attribute(:refresh_token_jti, jti)
+  end 
+
+end 

data/lib/henlo/revocable.rb

@@ -0,0 +1,28 @@
+#
+## Module allows the blacklist of tokens as identified by the jti (jwt identifier)
+## Blacklisted refresh tokens cannot be used to generate new id tokens
+module Henlo::Revocable 
+  
+  #
+  ## Method called when the identifier as encoded in the token payload does not match what was stored in the database
+  ## or when the revoke token route is called by the user in cases of breach such as device loss
+  ## the token is blacklisted and the resource is flagged as needing blacklist checks
+  def self.token_blockt(payload, resource)
+    resource.blacklist_check == true
+    resource.save!
+    
+    blacklisted_token = BlacklistedToken.create(
+      token_jti: payload["jti"],
+      exp_in_unix: payload["exp"]
+    )
+  end 
+  
+  #
+  ## Call this period in a scheduled task to clean expired tokens from the database
+  def self.token_rekt
+    BlacklistedToken.each do |token|
+      token.destroy unless Time.now.utc < token.exp_in_unix 
+    end   
+  end
+
+end 

data/lib/henlo/version.rb

@@ -0,0 +1,3 @@
+module Henlo
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,156 @@
+--- !ruby/object:Gem::Specification
+name: henlo
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- nombiezinja
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-01-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.2'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: knock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.1.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.1.1
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  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: Based on the Knock gem, offers options to further customize secure authentication
+  practices
+email:
+- tianyizhang1987@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Rakefile
+- lib/generators/henlo/install_generator.rb
+- lib/generators/henlo/migrations_generator.rb
+- lib/generators/templates/henlo_initializer.rb
+- lib/generators/templates/migrations/add_jti_column.rb
+- lib/generators/templates/migrations/create_blacklisted_tokens.rb.erb
+- lib/henlo.rb
+- lib/henlo/authenticable.rb
+- lib/henlo/helpers/util.rb
+- lib/henlo/identifiable.rb
+- lib/henlo/refreshable.rb
+- lib/henlo/revocable.rb
+- lib/henlo/version.rb
+homepage: https://github.com/nombiezinja/henlo
+licenses:
+- MIT
+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.4.0
+signing_key: 
+specification_version: 4
+summary: JWT based authentication with access and id tokens
+test_files: []