ak4r 0.2.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 30f9acbcce2837f1b5a58f93267a3a1fc36d329136b90cfeb30601f9e2603b3e
+  data.tar.gz: eb9615af834214a2c7b091b536ba5e1f334ed13cbe782448d2e1eb100054f336
+SHA512:
+  metadata.gz: f9345b35fd16afefe7063d8d6d7387d66fe7de9f0c441d940c9d402b1f32d148224db01560155d9156de3b6bf2ddc1248ec134896377d7b21f757eca016a72b2
+  data.tar.gz: 3e13a6875030f334bf4210847fec3739d50d8d6f2a14065a407b50fb1c19891948d71ae32e006091ba66ba5e9dc171dda54b76d4300e7b1f9acf5f0884aaaf83

data/README.md

@@ -0,0 +1,91 @@
+# AK4R = API Keys for Rails
+
+AK4R is a Rack middleware which adds to Ruby on Rails the ability to protect APi calls whit an API key passed in the request headers.
+
+The implementation is very similar to the description here: https://www.freecodecamp.org/news/best-practices-for-building-api-keys-97c26eabfea9/ ,
+using some pieces of the rack-api-key gem.
+
+API keys are stored in an Active Record model and validated at every request.
+
+API keys are scoped, so you have the ability to fine tune permissions.
+
+API keys can optionally expire.
+
+## Installation
+
+Add this line to your Rails application's Gemfile:
+
+    gem 'ak4r'
+
+And then execute:
+
+    $ bundle
+
+Finally you should generate the db migration:
+
+```ruby
+rails generate ak4r_migration
+rake db:migrate
+```
+
+## Usage
+
+Gem auto loads into the Rails application. The default is to protect all urls starting with "/api".
+Since initially no key is present every request throws an exception:
+
+```ruby
+Ak4r::ApiException
+```
+you should rescue this in your application, e.g. you can add this line to `application_controller.rb` :
+
+```ruby
+rescue_from Ak4r::ApiException, with: :handle_api_authorization
+```
+## How to generate API keys
+
+There is a rake task for this:
+
+```ruby
+rake ak4r:create["name","scope1;scope2"]
+```
+Scopes are defined as [HTTP_VERB]:path, e.g. `GET:/api/books.json` .
+
+This task outputs the key to put in X-API-KEY header. Please note that the key itself is not stored so you must immediatelly copy it in a secure place.
+
+## Configuration
+
+You can customize its behaviour in your `config/application.rb` :
+
+```ruby
+config.ak4r.[option] = '...'
+```
+
+If options depend on your environment, you can define it in the according file: `config/environments/<env>.rb`
+
+### :salt
+The salt used to generate keys.
+
+### :header_key
+It's important to note that internally Rack actually mutates any given headers
+and prefixes them with HTTP and subsequently underscores them. For example if an
+API client passed "X-API-KEY" in the header, Rack would interpret that header
+as "HTTP_X_API_KEY". "HTTP_X_API_KEY" is the default header. If you want to use
+a different header you can specify it with this option.
+
+### :url_restriction
+This is an option that can restrict the middleware to specific URLs.
+This works well when you have a mixture of API endpoints that require
+authentication and some that might not. Or a combination of API endpoints and
+publicly facing webpages. Perhaps you've scoped all of your API endpoints to
+"/api", and the rest of the URL mappings or routes are supposed to be wide open.
+
+### :url_exclusion
+This is an option to allow specific URLs to bypass middleware authentication.
+This works well when you require a single or few endpoints to not require
+authentication. Perhaps you've scoped all of your API endpoints to "/api" but wish
+to leave "/api/status" publicly facing.
+
+
+
+
+ 

data/lib/ak4r.rb

@@ -0,0 +1,12 @@
+require 'ak4r/configuration'
+require 'ak4r/railtie'
+
+module Ak4r
+  def self.configure
+    yield config
+  end
+
+  def self.config
+    @config ||= Configuration.new
+  end
+end

data/lib/ak4r/api_exception.rb

@@ -0,0 +1,9 @@
+class Ak4r::ApiException < Exception
+  attr_accessor :code
+  attr_accessor :response
+
+  def initialize(code, response)
+    @code = code
+    @response = response
+  end
+end 

data/lib/ak4r/api_key.rb

@@ -0,0 +1,6 @@
+module Ak4r
+  class ApiKey < ActiveRecord::Base
+    self.table_name = "ak4r_api_keys"
+  end
+end
+

data/lib/ak4r/configuration.rb

@@ -0,0 +1,31 @@
+module Ak4r
+  class Configuration
+    SETTINGS = [:salt, :header_key, :url_restriction, :url_exclusion]
+
+    SETTINGS.each do |setting|
+      attr_accessor setting
+
+      define_method "#{setting}?" do
+        ![nil, false, []].include? send(setting)
+      end
+    end
+
+    def initialize
+      @salt = "API_KEY_SALT"
+      @header_key = "HTTP_X_API_KEY"
+      @url_restriction = [/api/]
+      @url_exclusion = [/api\/status/]
+    end
+
+    def update(settings_hash)
+      settings_hash.each do |setting, value|
+        unless SETTINGS.include? setting.to_sym
+          raise ArgumentError, "invalid setting: #{setting}"
+        end
+
+        public_send "#{setting}=", value
+      end
+    end
+  end
+end
+ 

data/lib/ak4r/middleware.rb

@@ -0,0 +1,79 @@
+require 'ak4r'
+
+require 'ak4r/api_key'
+require 'ak4r/token_generator'
+require 'ak4r/api_exception'
+
+module Ak4r
+  class Middleware
+    ##
+    # ==== Options
+    # 
+    # * +:salt+ -             Salt to generate API keys.
+    #  
+    # * +:header_key+ -       A way to override the header's name used to store the API key.
+    #                         The value given here should reflect how Rack interprets the
+    #                         header. For example if the client passes "X-API-KEY" Rack
+    #                         transforms interprets it as "HTTP_X_API_KEY". The default
+    #                         value is "HTTP_X_API_KEY".
+    #
+    # * +:url_restriction+ -  A way to restrict specific URLs that should pass through
+    #                         the rack-api-key middleware. In order to use pass an Array of Regex patterns.
+    #                         If left unspecified all requests will pass through the rack-api-key
+    #                         middleware.
+    #
+    # * +:url_exclusion+ -    A way to exclude specific URLs that should not pass through the
+    #                         the rack-api-middleware. In order to use, pass an Array of Regex patterns.
+    #
+    # ==== Example
+    #   use Ak4r,
+    #       :salt => "API_KEY_SALT"
+    #       :header_key => "HTTP_X_API_KEY",
+    #       :url_restriction => [/api/],
+    #       :url_exclusion => [/api\/status/]
+    def initialize(app, config = {})
+      @app = app
+      Ak4r.config.update config
+    end
+
+    def call(env)
+      if constraint?(:url_exclusion) && url_matches(:url_exclusion, env)
+        @app.call(env)
+      elsif constraint?(:url_restriction)
+        url_matches(:url_restriction, env) ? process_request(env) : @app.call(env)
+      else
+        process_request(env)
+      end
+    end
+    
+    private
+
+    def process_request(env)      
+      api_key_string = env[Ak4r.config.header_key]
+      raise Ak4r::ApiException.new(403, "API Key required") if(api_key_string.nil?)
+
+      api_key_prefix, api_key_secret = api_key_string.split('.')
+      api_key = Ak4r::ApiKey.find_by(prefix: api_key_prefix)
+      raise Ak4r::ApiException.new(403, "API Key invalid") if(api_key.nil?)
+
+      raise Ak4r::ApiException.new(403, "API Key expired") if(api_key.valid_until && api_key.valid_until < Time.now)
+
+      api_key_hash = Ak4r::TokenGenerator.digest(api_key_secret)
+      raise Ak4r::ApiException.new(403, "API Key invalid") if(api_key_hash != api_key.hash)
+      
+      request = Rack::Request.new(env)
+      scope = "#{request.request_method}:#{request.path}"
+      raise Ak4r::ApiException.new(403, "API Key not allowed for scope #{scope}") unless(api_key.scopes.include?(scope))
+      @app.call(env)
+    end
+
+    def constraint?(key)
+      !(Ak4r.config.public_send(key).nil? || Ak4r.config.public_send(key).empty?)
+    end
+
+    def url_matches(key, env)
+      path = Rack::Request.new(env).fullpath
+      Ak4r.config.public_send(key).select { |url_regex| path.match(url_regex) }.empty? ? false : true
+    end
+  end
+end

data/lib/ak4r/railtie.rb

@@ -0,0 +1,15 @@
+module Ak4r
+  class Railtie < Rails::Railtie
+    config.ak4r = ActiveSupport::OrderedOptions.new
+
+    initializer 'ak4r.initialize' do |app|
+      require 'ak4r/middleware'
+      app.middleware.use Ak4r::Middleware, config.ak4r
+    end
+
+    rake_tasks do
+      load File.expand_path('../../tasks/ak4r.rake', __FILE__)
+    end
+  end
+end
+ 

data/lib/ak4r/token_generator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+require 'ak4r/api_key'
+
+# Adapted from Devise::TokenGenerator
+module Ak4r
+  class TokenGenerator
+    DIGEST = "SHA256"
+
+    def self.digest(value)
+      key = generate_key
+      value.present? && OpenSSL::HMAC.hexdigest(DIGEST, key, value.to_s)
+    end
+
+    def self.generate
+      key = generate_key
+      loop do
+        raw = self.friendly_token
+        enc = OpenSSL::HMAC.hexdigest(DIGEST, key, raw)
+        break [raw, enc] unless Ak4r::ApiKey.where(hash: enc).any?
+      end
+    end
+    
+    def self.generate_key
+      return  Rails.application.key_generator.generate_key(Ak4r.config.salt)
+    end
+
+    def self.friendly_token(length = 20)
+      # To calculate real characters, we must perform this operation.
+      # See SecureRandom.urlsafe_base64
+      rlength = (length * 3) / 4
+      SecureRandom.urlsafe_base64(rlength).tr('lIO0', 'sxyz')
+    end
+  end
+end 

data/lib/generators/ak4r_migration_generator.rb

@@ -0,0 +1,26 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+
+class Ak4rMigrationGenerator < Rails::Generators::Base
+  include Rails::Generators::Migration
+
+  desc 'Creates a new migration for Ak4r API keys'
+
+  def self.source_root
+    File.expand_path('../templates', __FILE__)
+  end
+
+  def self.next_migration_number(dirname)
+    if ActiveRecord::Base.timestamped_migrations
+      migration_number = Time.now.utc.strftime("%Y%m%d%H%M%S").to_i
+      migration_number += 1
+      migration_number.to_s
+    else
+      "%.3d" % (current_migration_number(dirname) + 1)
+    end
+  end
+
+  def create_migration_file
+    migration_template 'migration.rb', 'db/migrate/create_ak4r_api_key.rb'
+  end
+end

data/lib/generators/templates/migration.rb

@@ -0,0 +1,19 @@
+class CreateAk4rApiKey < ActiveRecord::Migration[4.2]
+  def self.up
+    create_table :ak4r_api_keys do |t|
+      t.string :name
+      t.string :prefix
+      t.string :hash
+      t.string :scopes, array: true
+      t.timestamp :valid_until
+      t.timestamps
+    end
+
+    add_index :ak4r_api_keys, :prefix
+    add_index :ak4r_api_keys, :hash
+  end
+
+  def self.down
+    drop_table :ak4r_api_keys
+  end
+end 

data/lib/tasks/ak4r.rake

@@ -0,0 +1,23 @@
+require 'ak4r/api_key'
+require 'ak4r/token_generator'
+
+namespace :ak4r do
+  desc "List all API Key"
+  task :list => :environment do
+    Ak4r::ApiKey.all.each do |api_key|
+      puts "#{api_key.name}\t#{api_key.prefix}\t#{api_key.scopes.join(";")}"
+    end
+  end
+  desc "Create new API Key"
+  task :create, [:name, :scopes] => :environment do    
+    secret, hash = Ak4r::TokenGenerator.generate
+    api_key = Ak4r::ApiKey.create(
+      name: args[:name],
+      hash: hash,
+      prefix: Ak4r::TokenGenerator.friendly_token(7),
+      scopes:  args[:scopes].split(';')
+    )
+    puts "#{api_key.prefix}.#{secret}"
+  end
+end
+ 

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: ak4r
+version: !ruby/object:Gem::Version
+  version: 0.2.2
+platform: ruby
+authors:
+- Stefano Salvador
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2021-02-04 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'
+description: Middleware for adding api keys validation to API
+email: stefano.salvador@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/ak4r.rb
+- lib/ak4r/api_exception.rb
+- lib/ak4r/api_key.rb
+- lib/ak4r/configuration.rb
+- lib/ak4r/middleware.rb
+- lib/ak4r/railtie.rb
+- lib/ak4r/token_generator.rb
+- lib/generators/ak4r_migration_generator.rb
+- lib/generators/templates/migration.rb
+- lib/tasks/ak4r.rake
+homepage: https://github.com/stefanosalvador/ak4r
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key: 
+specification_version: 4
+summary: API Keys for Ruby on Rails
+test_files: []