cadinsor 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f272eb0fca093ecb854ed3e0095fbaa11601be92
+  data.tar.gz: e527755a81a9c143c407a9c9cba4f61054b4659f
+SHA512:
+  metadata.gz: 61236189e79b581f1c004912d393bdf6579325566ef404319bd1a150a8e54e884f35beb56f12ec24a6a70dc45ed6f017af889d4bc24e80d4323ee7405cbd4d42
+  data.tar.gz: ec34b71995bfb135ca902e7dedb52af17fd605fdd7ee969b7d5b62966e15e92ece962b5a2e5fbe9a2099e3f84f6dee91773eaf74f8a1eb007e41c552408b95df

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2014 Ramkumar V.
+
+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,109 @@
+Cadinsor 0.1.0
+===
+## What is Cadinsor?
+Cadinsor provides OAuth like authentication to validate requests from your client apps to your backend Rails application. It can be easily mounted onto any application as it is a Rails engine. Currently supports both JSON and XML formats.
+
+## Setup Instructions
+  Add the cadinsor gem your gem file and then run the install generator. The installer will ask you would like to mount the engine.
+
+
+    gem "cadinsor"
+    $ rails g cadinsor:install
+    $ rake db:migrate
+
+## So how does it work?
+Every request that is authenticated through Cadinsor must possess among it's parameters:
+
+  1. A valid server issued key
+
+  2. A valid app id
+
+  3. A proper request signature
+
+### Key Components
+  * **An APP ID/ Secret**: Each client application has a unique APP ID and an "APP Secret" string. The app id is sent as part of every request from the client app. The app secret is not sent with the request, and is instead used to build the request signature (explained below).
+  Cadinsor has very helpful rake tasks for you to manager your apps. Please be warned that the client_app tasks are interactive and cannot be run in a background job. You may run the following rake tasks:
+
+      rake cadinsor:client_app:create         # Add a new client app
+      rake cadinsor:client_app:delete         # Delete App
+      rake cadinsor:client_app:edit_secret    # Edit App Secret
+      rake cadinsor:client_app:list           # List all client apps with their secrets
+
+  * **A Server Issued Key/ Key Fetch API**: In order to keep each request from the app independent, a server issued unique key string is sent along with request. A key is obtained by making a call the Key Fetch API. It is a public API and requires no parameters except an optional app id. The key has a time bound expiry (default = 5mins, specified in the initializer) and is invalidated after each request to the backend application.
+
+    + Assuming your engine is mounted at /cadinsor, you may get a new key by visiting <root_url>/cadinsor/api_keys/create.json
+    + Assuming your engine is mounted at /cadinsor, you may view the status of your key by visiting <root_url>/cadinsor/api_keys/show.json?key=<key value here\>
+
+You can clear expired keys from the db in the background or foreground by using rake tasks:
+
+    rake cadinsor:api_key:clean_background  # Remove all expired keys from the db without any confirmation, for background tasks like cron jobs only
+    rake cadinsor:api_key:clean_manual      # Interactive task to remove expired keys from the db, please use clean_background if you want to run this in a non-interactive mode
+
+
+### Building the request signature at the client side
+All the request parameters are sorted in alphabetical order and a request string is obtained by concatenating the corresponding values of these parameters. To this string, the app secret and an SHA2 (256 bit) hash is computed of this string. This signature is also sent with every request to the server.
+Ex: Consider a simple login request with the following parameters:
+
+  1. user_name: lewstherin
+  2. password: thedragon
+  3. key: N1ilN8qZmOXodohO-9IRvpxZmVDY_Zg8P7r9JoDpFs4
+  4. app_id: 2
+
+In alphabetical order, these parameters become app_id, key, password and user_name. Assuming the app secret is "CaraianCaldazar!", our request string becomes "2N1ilN8qZmOXodohO-9IRvpxZmVDY_Zg8P7r9JoDpFs4thedragonlewstherinCaraianCaldazar!". Now the SHA2 hash of this string is "ab71fc84351c4cdfd23c31ea2ce4133b38cd3c21cfee48d3d15501e726c16734" and this is sent along with the request as the parameter signature.
+At the server end, Cadinsor will rebuild this signature and check if it matches with the input signature. If it does, it means the client has sent a valid app secret and thus the request is from a trusted source.
+
+In case you have nested hashes, flatten them by appending the outer hash key as a prefix, and then sort the keys to build a signature.
+Ex: If your input params is as follows, cadinsor computes the signature of the flattened hash shown below.
+
+    params = {:key=>"aslkaslkas", :signature=>"askjaskdskjdasklfj2103", :user=>{:id=>1, :email=>"a@b.com"}, :post=>{:title=>"rails_layout", :author=>"lewstherin", :comments=>{:author=>"Lews Therin", :date=>"14012014", :desc=>"This is a dummy comment"}}}
+
+    flattened_hash = {"key"=>"aslkaslkas", "signature"=>"askjaskdskjdasklfj2103", "user_id"=>1, "user_email"=>"a@b.com", "post_title"=>"rails_layout", "post_author"=>"lewstherin", "post_comments_author"=>"Lews Therin", "post_comments_date"=>"14012014", "post_comments_desc"=>"This is a dummy comment"}
+
+### Validating your requests at the controller side
+
+You can validate your requests by the either placing a call to the **check_request_with_cadinsor** method in the before_filter method of your controller or by making an explicit call within your method. Take a look at the following code snippet (same code as in the test/dummy application):
+
+    class CadinsorTestsController < ApplicationController
+
+      before_filter :check_request_with_cadinsor, except: [:inside_method_check, :do_not_check]
+
+      def default_check
+        respond_to do  |format|
+          format.json {render :action => 'do_not_check', :format => 'json'}
+          format.xml {render :action => 'do_not_check', :format => 'xml'}
+        end
+      end
+
+      def inside_method_check
+        check_request_with_cadinsor
+        respond_to do  |format|
+          format.json {render :action => 'do_not_check', :format => 'json'}
+          format.xml {render :action => 'do_not_check', :format => 'xml'}
+        end
+      end
+
+      def do_not_check
+        respond_to do  |format|
+          format.json {render :action => 'do_not_check', :format => 'json'}
+          format.xml {render :action => 'do_not_check', :format => 'xml'}
+        end
+      end
+    end
+
+### Options while calling the *check_request_with_cadinsor_method*
+
+  1. If you do not want the cadinsor to check the params hash, but would like to check some other hash, you can do that by calling the method as follows:
+
+        check_request_with_cadinsor(target_params: params[user])
+
+  2. You can disable key checking altogether by:
+
+        check_request_with_cadinsor(ignore_api_key_check: true)
+
+## Action Items
+
+  1. Add tests
+  2. Improve this documentation
+
+## License
+[MIT License](http://opensource.org/licenses/MIT)

data/README.rdoc

@@ -0,0 +1,3 @@
+= Cadinsor
+
+This project rocks and uses MIT-LICENSE.

data/Rakefile

@@ -0,0 +1,34 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Cadinsor'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task default: :test

data/app/controllers/cadinsor/api_keys_controller.rb

@@ -0,0 +1,29 @@
+require_dependency "cadinsor/application_controller"
+
+module Cadinsor
+  class ApiKeysController < ApplicationController
+
+    def create
+      @key = ApiKey.new
+      @key.client_app_id = params[Cadinsor::Engine.config.api_key_param_name].to_i if params[Cadinsor::Engine.config.api_key_param_name]
+      @key.generate_key!
+      if @key.save
+        respond_to do |format|
+          format.json {redirect_to :action => 'show', :format => 'json', :key => @key.key}
+          format.xml {redirect_to :action => 'show', :format => 'xml', :key => @key.key}
+        end
+      else
+        respond_to do |format|
+          format.json
+          format.xml
+        end
+      end
+    end
+
+    def show
+      if params[:key]
+        @key = ApiKey.find_by_key(params[:key])
+      end
+    end
+  end
+end

data/app/controllers/cadinsor/application_controller.rb

@@ -0,0 +1,4 @@
+module Cadinsor
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/helpers/cadinsor/api_keys_helper.rb

@@ -0,0 +1,4 @@
+module Cadinsor
+  module ApiKeysHelper
+  end
+end

data/app/helpers/cadinsor/application_helper.rb

@@ -0,0 +1,4 @@
+module Cadinsor
+  module ApplicationHelper
+  end
+end

data/app/models/cadinsor/api_key.rb

@@ -0,0 +1,19 @@
+module Cadinsor
+  class ApiKey < ActiveRecord::Base
+    belongs_to :client_app
+    validates_presence_of :key
+
+    def generate_key!
+      self.key = SecureRandom.urlsafe_base64(32)
+      generate_key! if Cadinsor::ApiKey.find_by_key(self.key)
+      # Return object for chaining requests
+      self
+    end
+
+    def expired?
+      return true if self.created_at < Cadinsor::Engine.config.key_expiry_time_in_mins.to_i.minutes.ago
+      false
+    end
+
+  end
+end

data/app/models/cadinsor/client_app.rb

@@ -0,0 +1,13 @@
+module Cadinsor
+  class ClientApp < ActiveRecord::Base
+    validates_presence_of :name,:secret
+    validates_uniqueness_of :name, :secret
+
+    def generate_secret!
+      self.secret = SecureRandom.urlsafe_base64(32)
+      generate_secret! if ClientApp.find_by_secret(self.secret)
+      self
+    end
+
+  end
+end

data/app/views/cadinsor/api_keys/create.rabl

@@ -0,0 +1,3 @@
+object @key
+node(:status) {"Error."}
+node(:errors) {|key| key.errors.full_messages}

data/app/views/cadinsor/api_keys/show.rabl

@@ -0,0 +1,10 @@
+object @key
+if !@key
+  node(:status) {"Error."}
+  node(:errors) {"No valid key found with id: " + params[:id].to_s}
+else
+  node(:status) {"Success."}
+  attribute :key
+  attribute :created_at
+  node(:expired) {|key| key.expired?}
+end

data/app/views/cadinsor/application/cadinsor_error_response.rabl

@@ -0,0 +1,3 @@
+object :false
+node(:status) {"Error."}
+node(:errors) {@cadinsor_error_message}

data/app/views/layouts/cadinsor/application.html.erb

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Cadinsor</title>
+  <%= stylesheet_link_tag    "cadinsor/application", media: "all" %>
+  <%= javascript_include_tag "cadinsor/application" %>
+  <%= csrf_meta_tags %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/config/initializers/rabl_config.rb

@@ -0,0 +1,4 @@
+require 'rabl'
+Rabl.configure do |config|
+  config.include_json_root = false
+end

data/config/routes.rb

@@ -0,0 +1,4 @@
+Cadinsor::Engine.routes.draw do
+  get 'api_keys/create', :responds => [:json, :xml]
+  get 'api_keys/show', :responds => [:json, :xml]
+end

data/db/migrate/20140111160304_create_cadinsor_client_apps.rb

@@ -0,0 +1,9 @@
+class CreateCadinsorClientApps < ActiveRecord::Migration
+  def change
+    create_table :cadinsor_client_apps do |t|
+      t.string :name
+      t.string :secret
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20140111160653_create_cadinsor_api_keys.rb

@@ -0,0 +1,10 @@
+class CreateCadinsorApiKeys < ActiveRecord::Migration
+  def change
+    create_table :cadinsor_api_keys do |t|
+      t.string :key
+      t.integer :client_app_id
+      t.timestamps
+    end
+    add_index :cadinsor_api_keys, :key
+  end
+end

data/lib/cadinsor.rb

@@ -0,0 +1,6 @@
+require "cadinsor/engine"
+require "cadinsor/extensions"
+require "cadinsor/extensions/request_error"
+
+module Cadinsor
+end

data/lib/cadinsor/engine.rb

@@ -0,0 +1,10 @@
+module Cadinsor
+  class Engine < ::Rails::Engine
+    isolate_namespace Cadinsor
+    # Set key expiry time in minutes
+    self.config.key_expiry_time_in_mins = 5
+    self.config.client_app_id_param_name = :client_app_id
+    self.config.api_key_param_name = :api_key
+    self.config.request_signature_param_name = :signature
+  end
+end

data/lib/cadinsor/extensions.rb

@@ -0,0 +1,61 @@
+module Cadinsor
+  module Extensions
+
+    def check_request_with_cadinsor(options = {})
+      options[:target_params] ? target_params = options[:target_params] : target_params = params
+      target_params = cadinsor_flatten_params(target_params)
+      api_key = target_params[Cadinsor::Engine.config.api_key_param_name.to_s]
+      signature = target_params[Cadinsor::Engine.config.request_signature_param_name.to_s]
+      client_app_id = target_params[Cadinsor::Engine.config.client_app_id_param_name.to_s]
+      cadinsor_validate_key(api_key) if options[:ignore_api_key_check] != true
+      cadinsor_validate_app(client_app_id)
+      cadinsor_validate_signature(target_params, signature, Cadinsor::Engine.config.client_app_id_param_name.to_s, Cadinsor::Engine.config.request_signature_param_name.to_s)
+    end
+
+    def cadinsor_flatten_params(parameter_hash, key_prefix = "")
+      flattened_hash = {}
+      parameter_hash.keys.each do |key|
+        if parameter_hash[key].is_a? Hash
+          key_prefix == "" ? flatten_prefix = key.to_s : flatten_prefix = key_prefix + "_" + key.to_s
+          flattened_hash.merge! cadinsor_flatten_params(parameter_hash[key], flatten_prefix)
+        else
+          key_prefix == "" ? flattened_hash.merge!({key.to_s => parameter_hash[key]}) : flattened_hash.merge!({(key_prefix.to_s + "_" + key.to_s) => parameter_hash[key]})
+        end
+      end
+      flattened_hash
+    end
+
+    def cadinsor_validate_key(api_key)
+      raise Cadinsor::Extensions::RequestError.new "Invalid Request. Key not present in request." if api_key.to_s == ""
+      key = Cadinsor::ApiKey.find_by_key(api_key)
+      raise Cadinsor::Extensions::RequestError.new "Invalid Request. Key is not valid." if !key
+      raise Cadinsor::Extensions::RequestError.new "Invalid Request. Key has expired. Please use a new key." if key.expired?
+    end
+
+    def cadinsor_rescue(message)
+      @cadinsor_error_message = message
+      respond_to do |format|
+        format.json {render "cadinsor/application/cadinsor_error_response", format: 'json'}
+        format.xml {render "/cadinsor/application/cadinsor_error_response", format: 'xml'}
+      end
+    end
+
+    def cadinsor_validate_app(app_id)
+      raise Cadinsor::Extensions::RequestError.new "Invalid Request. Client App id is not present in request." if app_id.to_s == ""
+      app = Cadinsor::ClientApp.find_by_id(app_id)
+      raise Cadinsor::Extensions::RequestError.new "Invalid Request. Client App is not valid." if !app
+    end
+
+    def cadinsor_validate_signature(params, signature, app_id_param_name, signature_param_name)
+      raise Cadinsor::Extensions::RequestError.new "Invalid Request. Request signature is not present." if signature.to_s == ""
+      req_string = ""
+      params.keys.sort.each do |key|
+        req_string = req_string + params[key] unless [signature_param_name.to_s, "controller", "action", "format"].include? key.to_s
+      end
+      req_string = req_string + Cadinsor::ClientApp.find_by_id(params[app_id_param_name.to_s]).secret
+      request_hash = Digest::SHA2.hexdigest(req_string)
+      raise Cadinsor::Extensions::RequestError.new "Invalid Request. Request Signature is not valid." if signature != request_hash
+    end
+
+  end
+end

data/lib/cadinsor/extensions/request_error.rb

@@ -0,0 +1,6 @@
+module Cadinsor
+  module Extensions
+    class RequestError < StandardError
+    end
+  end
+end

data/lib/cadinsor/version.rb

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

data/lib/generators/cadinsor/install/USAGE

@@ -0,0 +1,7 @@
+Description:
+  This generator will create an initializer called cadinsor.rb in config/initializers, which is necessary for running the Cadinsor gem.
+  Please visit the github page: http://github.com/lewstherin/cadinsor for more details on the various configuration options etc.
+
+  Do not forget to run rake db:migrate after running this initializer.
+
+