grape_token_auth 0.0.0 → 0.1.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b5f9b48e1bba210e29f6f544cb7c2c132fa4bc7d
-  data.tar.gz: 717533ea3acd49d9a4e019bad61fa8efc7b76b17
+  metadata.gz: ddbd0d988786f926a723d58429d2b7dd79d558f9
+  data.tar.gz: b075458cd909456ea27c1c72b4dae44c4f788036
 SHA512:
-  metadata.gz: 89f83a60e3502b534041c875201c45e5912edc464aa9a55d84b5f0dad316e7c67e030eee7244559593eed2b6f303272144f454adcb877fb96b73a9f89db649ab
-  data.tar.gz: 9b894b55b83a04f34b1c9cb4707a120fe6341c8fd238574d7e6c56b130d9de278e61befac48b75c4c057814ebf7086a5c04b141a6c9603a65d8737eb07e9e795
+  metadata.gz: f7d689f290b5ff831bd32ff9eaffcdf6f8af0f409366d11031bfcd77abaf5fd8d567cbc0245c08450cc83991db925005d88c83feb2d25559922b85853cc06397
+  data.tar.gz: 9ed0e47470c0c50ecf0d4046ac6a36edd093fe101dc2ca298337027041e14fe5c75388dc3399120ef83d2cd2c2036fa2e355bf985a231db5793a3bd2e79d96fe

data/.rspec

@@ -1,2 +1,2 @@
---format documentation
 --color
+--require spec_helper

data/.ruby-version

@@ -0,0 +1 @@
+2.2.0

data/CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing
+
+Fork, then clone the repo:
+
+    git clone git@github.com:your-username/grape_token_auth.git
+
+Set up your machine:
+
+    ./bin/setup
+
+Make sure the tests pass:
+
+    ./bin/rspec
+
+Make your changes and add tests for your change. I use [rubocop][rc] with the default
+style guide for consistency.
+
+Make sure the tests pass before committing:
+
+    ./bin/rspec
+
+##Git committing
+
+I prefer short, atomic commits. Obviously, this isn't a deal breaker but I
+believe it makes for a better repo. When writing git messages, refer to this
+[great post by Tim Pope][gc]. As a small addendum, I try to begin each message
+with one of the following words:
+
+- Add
+- Modify
+- Re-factor
+- Fix
+- Remove
+- Tidy
+- Update
+
+I find this expresses the intent of the commit and also helps keep things
+atomic. I picked this trick up from this
+[post](https://github.com/rails/rails/blob/master/CONTRIBUTING.md).
+
+
+Push to your fork and [submit a pull request][pr].
+
+[gc]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
+[rc]: https://github.com/bbatsov/rubocop
+[pr]: https://github.com/mcordell/grape_token_auth/compare/

data/README.md

@@ -1,8 +1,29 @@
 # GrapeTokenAuth
+[![Code Climate GPA][11]][12] [![Test Coverage][13]][14] [![Circle CI][15]][16]
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/grape_token_auth`. To experiment with that code, run `bin/console` for an interactive prompt.
+> __This gem is in active development__ but approaching a 0.1.0 release. If you
+are interested in helping out, please clone the release candidate and submit issues
+and PRs to help get it into a production-ready state!
 
-TODO: Delete this and the text above, and describe your gem
+GrapeTokenAuth is a token authentication solution for grape. It is compatible
+with [ng-token-auth][1] (for _angular_) and [j-toker][2] (for _jQuery_), and is
+meant as a [grape][4] (rather than _rails_) version of [devise_token_auth][3]. As
+such, this project is built entirely upon _grape_ and [warden][9] and avoids the
+need for _rails_. However, it has built in compatibility for [devise][devise] if
+you are looking to mount a grape app within your rails app. Finally, If you are
+placing a grape app within an existing _rails_ + _devise\_token\_auth_ app you might
+be interested in [grape_devise_token_auth][5].
+
+This gem is a port of [devise_token-auth][4] written by [Lyann Dylan Hurley][6]
+and [the team of contributors][dta-contributors]. That team does great work and
+the [conceptual section on that gem][7] is highly recommended reading.
+
+_Philosophy_
+
+This gem aims to maintain a small direct dependency footprint. As such, it
+currently depends only on _grape_, _warden_, _mail_, and _bcrypt_. In the
+future, the hope is to break this gem up into modules so that you can be even
+more selective on the code and dependencies that are included.
 
 ## Installation
 
@@ -14,26 +35,215 @@ gem 'grape_token_auth'
 
 And then execute:
 
-    $ bundle
+$ bundle
 
 Or install it yourself as:
 
-    $ gem install grape_token_auth
+$ gem install grape_token_auth
+
+## Quick-Start Setup
+
+This is the minimum setup to get _GrapeTokenAuth_ running. For a more
+detailed walkthrough, you can refer to this [blog post][gta-setup], the [demo
+repo][demo-repo], and the [wiki][gta-wiki]. Setup has 4 parts:
+
+1. [Middleware Setup](#middlewaresetup)
+2. [Model/ORM setup](#modelormsetup)
+3. [Grape Token Auth configuration](#grapetokenauthconfiguration)
+4. [Mounting Authentication APIs](#mountingauthenticationapis)
+
+###Middleware setup
+
+_GrapeTokenAuth_ requires setting up _warden_ middleware in order to function
+properly. In a simple _rack_ environment this is usually as easy as adding the
+following to the `config.ru`:
+
+```ruby
+# config.ru
+
+require 'warden'
+require 'grape_token_auth'
+
+## Setup session middleware (E.g. Rack::Session::Cookie)
+
+GrapeTokenAuth.setup_warden!(self)
+
+run YourGrapeAPI
+```
+
+In _rails_, you will need to setup warden as so:
+
+```ruby
+# application.rb
+
+config.middleware.insert_after ActionDispatch::Flash, Warden::Manager do |manager|
+  manager.failure_app = GrapeTokenAuth::UnauthorizedMiddleware
+  manager.default_scope = :user
+  GrapeTokenAuth.configure_warden(manager)
+end
+```
+
+### Model/ORM setup
+
+Include the module for your ORM within the model classes. At the moment, only
+ActiveRecord is supported but other ORMs are planned. Your model must
+contain a text-type field called `tokens`.
+
+####ActiveRecord
+
+```ruby
+class User < ActiveRecord::Base
+  include GrapeTokenAuth::ActiveRecord::TokenAuth
+end
+```
+
+### Grape Token Auth Configuration
+
+GTA does not make guesses about what scopes and user classes you are using, you
+must define them before the Grape API is loaded. In _rails_ this could be in an
+initializer, for a rack app run the setup before the API class definitions.
+
+To define mappings, the scope is the key of the mapping hash, and the value is the
+model to which the scope is mapped. For the above user class this would be:
+
+```ruby
+GrapeTokenAuth.setup! do |config|
+	config.mappings = { user: User }
+	config.secret   = 'THIS MUST BE A LONG HEX STRING'
+end
+```
+
+**Note on Secret**: generate a unique secret using `rake secret` in a rails app
+or via [these directions][secret].
+
+
+### Mounting authentication APIs
+
+In order to use a given feature of GrapeTokenAuth, the corresponding API must be
+mounted. This can be accomplished in your grape app by first including the mount
+helpers:
+
+
+```ruby
+class TestApp < Grape::API
+  format :json
+
+  include GrapeTokenAuth::MountHelpers
+
+  #...
+end
+```
+
+Then you can use the individual helpers to mount a given GTA API:
+
+```ruby
+class TestApp < Grape::API
+  # ...
+
+  mount_registration(to: '/auth', for: :user)
+  mount_session(to: '/auth', for: :user)
+  mount_token_validation(to: '/auth', for: :user)
+  mount_confirmation(to: '/auth', for: :user)
+
+  # ...
+end
+```
+
+The first line indicates the _GrapeTokenAuth_ registration API will be mounted
+to '/auth' relative to the location where the TestApp is mounted. Presuming that
+TestApp is being run at root, registration endpoints will be at `/auth`. Also,
+we are defining the scope that these endpoints pertain to (user). **Important**
+the scope must be defined in the [configuration
+step](#grapetokenauthconfiguration).
+
+A table of the various APIs and their associated helpers follows:
+
+| API | helper | description |
+| --- | --- | --- |
+| Registration         | `mount_registration` | used to register new 'email' type users |
+| Session              | `mount_sessions`     | used to login 'email' type users        |
+| Confirmation | `mount_confirmation` | used to confirm 'email' users new emails |
+| TokenValidation      | `mount_token_validation`      | used to tokens for all type users        |
+| OmniAuth | `mount_omniauth` | used to register/login omniauth users, requires the OmniAuthCallback API |
+| OmniAuthCallback | `mount_omniauth_callbacks` |  used to register/login omniauth users, requires the OmniAuth API|
+| PasswordReset | `mount_password_reset` | used to issue password resets for forgotten passwords|
 
 ## Usage
 
-TODO: Write usage instructions here
+First, include the `TokenAuthentication` module in the _grape_ API you want to
+enforce authentication on.
+
+```ruby
+class TestApp < Grape::API
+  # ...
+
+  include GrapeTokenAuth::TokenAuthentication
+
+  # ...
+end
+```
+
+### Enforcing authentication on an endpoint
+
+In any _grape_ endpoint you can call `authenticate_{SCOPE}!` to enforce
+authentication on that endpoint. For instance, the following:
+
+```ruby
+get '/' do
+  authenticate_user!
+  present Post.all
+end
+```
+
+will authenticate against the `:user` scope when trying to GET the `/` route.
+
+
+### Enforcing authentication on all endpoints
+
+Alternatively, if you want to protect all of the endpoints in an API, place
+the authentication call in a `before_filter`, like so:
+
+```ruby
+class TestApp < Grape::API
+  before do
+    :authenticate_user!
+  end
+end
+```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then,
+run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To run tests, you will need postgres to be setup and configured correctly.  Run
+`rake db:setup` to create the test db and `rake db:reset` to reset the db.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release` to create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-1. Fork it ( https://github.com/[my-github-username]/grape_token_auth/fork )
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
+[See CONTRIBUTING.md][contributing]
+
+[1]: https://github.com/lynndylanhurley/ng-token-auth
+[2]: https://github.com/lynndylanhurley/j-toker
+[3]: https://github.com/lynndylanhurley/devise_token_auth
+[4]: https://github.com/intridea/grape
+[5]: https://github.com/mcordell/grape_devise_token_auth
+[6]: https://github.com/lynndylanhurley
+[7]: https://github.com/lynndylanhurley/devise_token_auth#conceptual
+[8]: https://rubygems.org
+[9]: https://github.com/hassox/warden
+[10]: https://github.com/mcordell/grape_token_auth/milestones/Devise%20Token%20Auth%20Functional%20Parity
+[11]: https://codeclimate.com/github/mcordell/grape_token_auth/badges/gpa.svg
+[12]: https://codeclimate.com/github/mcordell/grape_token_auth
+[13]: https://codeclimate.com/github/mcordell/grape_token_auth/badges/coverage.svg
+[14]: https://codeclimate.com/github/mcordell/grape_token_auth/coverage
+[15]: https://circleci.com/gh/mcordell/grape_token_auth.svg?style=svg
+[16]: https://circleci.com/gh/mcordell/grape_token_auth
+[contributing]: https://github.com/mcordell/grape_token_auth/blob/master/CONTRIBUTING.md
+[gta-wiki]: https://github.com/mcordell/grape_token_auth/wiki
+[demo-repo]: https://github.com/mcordell/grape_token_auth_demo
+[gta-setup]: http://blog.mikecordell.com/grape-token-auth/2015/09/15/setting-up-authentication-on-a-grape-api-with-grapetokenauth.html
+[secret]: http://www.jamesbadger.ca/2012/12/18/generate-new-secret-token/
+[dta-contributors]: https://github.com/lynndylanhurley/devise_token_auth#callouts
+[devise]: https://github.com/plataformatec/devise

data/Rakefile

@@ -1,2 +1,12 @@
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'
+require_relative './spec/database'
 
+namespace :db do
+  task :setup do
+    Database.setup
+  end
+
+  task :reset do
+    Database.reset
+  end
+end

data/bin/rspec

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rspec-core', 'rspec')

data/circle.yml

@@ -0,0 +1,6 @@
+database:
+  override:
+    - bundle exec rake db:setup; bundle exec rake db:reset
+test:
+  override:
+    - ./bin/rspec

data/config/database.yml

@@ -0,0 +1,8 @@
+test:
+  adapter: postgresql
+  database: gta_test
+  pool: 5
+  timeout: 5000
+  host: localhost
+  username: tester
+  password: password1

data/grape_token_auth.gemspec

@@ -18,6 +18,21 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
+  spec.add_dependency 'grape', '~> 0.9.0'
+  spec.add_dependency 'warden', '~> 1.2.3'
+  spec.add_dependency 'bcrypt', '~> 3.0'
+  spec.add_dependency 'mail',   '~> 2.0'
+  spec.add_development_dependency 'activerecord'
   spec.add_development_dependency 'bundler', '~> 1.8'
+  spec.add_development_dependency 'codeclimate-test-reporter'
+  spec.add_development_dependency 'database_cleaner'
+  spec.add_development_dependency 'factory_girl'
+  spec.add_development_dependency 'omniauth'
+  spec.add_development_dependency 'omniauth-facebook'
+  spec.add_development_dependency 'pry'
+  spec.add_development_dependency 'pg'
   spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rack-test'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'timecop'
 end

data/lib/grape_token_auth/api_helpers.rb

@@ -0,0 +1,30 @@
+module GrapeTokenAuth
+  module ApiHelpers
+    def self.included(base)
+      GrapeTokenAuth.configuration.mappings.keys.each do |scope, _resource_class|
+        define_method("current_#{scope}") do
+          authorizer_data.fetch_stored_resource(scope)
+        end
+
+        define_method("authenticate_#{scope}!") do
+          token_authorizer = TokenAuthorizer.new(authorizer_data)
+          resource = token_authorizer.authenticate_from_token(scope)
+          fail Unauthorized unless resource
+          env['rack.session'] ||= {}
+          authorizer_data.store_resource(resource, scope)
+          resource
+        end
+      end
+    end
+
+    def authorizer_data
+      @authorizer_data ||= AuthorizerData.from_env(env)
+    end
+
+    def authenticated?(scope = :user)
+      user_type = "current_#{scope}"
+      return false unless respond_to?(user_type)
+      !!send(user_type)
+    end
+  end
+end

data/lib/grape_token_auth/apis/confirmation_api.rb

@@ -0,0 +1,49 @@
+module GrapeTokenAuth
+  # Module that contains the majority of the email confirming functionality.
+  # This module can be included in a Grape::API class that defines a
+  # resource_scope and therefore have all of the functionality with a given
+  # resource (mapping).
+  module ConfirmationAPICore
+    def self.included(base)
+      base.get do
+        resource_class = GrapeTokenAuth.configuration.scope_to_class(
+          base.resource_scope)
+        resource = resource_class.confirm_by_token(params[:confirmation_token])
+
+        if resource.persisted?
+          token = Token.new
+
+          resource.tokens[token.client_id] = {
+            token:  token.to_password_hash,
+            expiry: token.expiry
+          }
+
+          resource.save!
+
+          redirect_url = resource.build_auth_url(
+            params[:redirect_url], token: token.to_s,
+                                   account_confirmation_success: true,
+                                   client_id: token.client_id,
+                                   config: params[:config])
+
+          redirect redirect_url
+        else
+          error!({ errors: 'Unable to find confirmation.',
+                   status: 'error' }, 404)
+        end
+      end
+    end
+  end
+
+  # "Empty" Confirmation API where OmniAuthAPICore is mounted, defaults to
+  # a :user resource class
+  class ConfirmationAPI < Grape::API
+    class << self
+      def resource_scope
+        :user
+      end
+    end
+
+    include ConfirmationAPICore
+  end
+end

data/lib/grape_token_auth/apis/omniauth_api.rb

@@ -0,0 +1,149 @@
+module GrapeTokenAuth
+  # Module that contains the majority of the OmniAuth functionality. This module
+  # can be included in a Grape::API class that defines a resource_scope and
+  # therefore have all of the functionality with a given resource (mapping).
+  module OmniAuthAPICore
+    def self.included(base)
+      base.helpers do
+        def auth_hash
+          @auth_hash ||= request.env['rack.session'].delete('gta.omniauth.auth')
+        end
+
+        def omniauth_params
+          @omniauth_params ||= request.env['rack.session']
+                               .delete('gta.omniauth.params')
+        end
+
+        def render_html(html)
+          env['api.format'] = :html
+          content_type 'text/html; charset=utf-8'
+          html
+        end
+
+        def sign_in_resource(resource, scope)
+          request.env['warden'].session_serializer.store(resource, scope)
+        end
+
+        def redirect_or_render(success_html)
+          if %w(inAppBrowser newWindow).include?(success_html.window_type)
+            render_html(success_html.render_html)
+          elsif success_html.auth_origin_url
+            # default to same-window implementation, which forwards back to
+            # auth_origin_url build and redirect to destination url
+            redirect success_html.full_redirect_url
+          else
+            # there SHOULD always be an auth_origin_url, but if someone does
+            # something silly like coming straight to this url or refreshing the
+            # page at the wrong time, there may not be one. In that case, just
+            # render in plain text the error message if there is one or
+            # otherwisei a generic message.
+            fallback_render 'An error occurred'
+          end
+        end
+
+        def fallback_render(text)
+          render_html <<-EOD
+            <html>
+                    <head></head>
+                    <body>
+                            #{text}
+                    </body>
+            </html>
+          EOD
+        end
+      end
+
+      base.desc 'resource redirector for initial auth attempt' do
+        detail <<-EOD
+        Sets up the proper resource classes as a query parameter that is then
+        passed along to the proper OmniAuth provider app.
+        EOD
+      end
+      base.get ':provider' do
+        qs = CGI.parse(request.env['QUERY_STRING'])
+        qs['resource_class'] = [base.resource_scope]
+        query_params = qs.each_with_object({}) do |args, hsh|
+          hsh[args[0]] = args[1].first
+        end.to_param
+        omni_prefix = ::OmniAuth.config.path_prefix
+        path = "#{omni_prefix}/#{params[:provider]}?#{query_params}"
+        redirect path
+      end
+
+      base.desc 'OmniAuth success endpoint'
+      base.get ':provider/callback' do
+        fail unless omniauth_params
+        fail unless auth_hash
+        resource_class = GrapeTokenAuth.configuration
+                         .scope_to_class(base.resource_scope)
+        success_html = OmniAuthSuccessHTML.build(resource_class,
+                                                 auth_hash,
+                                                 omniauth_params)
+        if success_html.persist_oauth_attributes!
+          sign_in_resource(success_html.resource, base.resource_scope)
+          redirect_or_render(success_html)
+        else
+          status 500
+        end
+      end
+    end
+  end
+
+  # "Empty" OmniAuth API where OmniAuthAPICore is mounted, defaults to a :user
+  # resource class
+  class OmniAuthAPI < Grape::API
+    class << self
+      def resource_scope
+        :user
+      end
+    end
+
+    include OmniAuthAPICore
+  end
+
+  # Upon a callback from the OmniAuth provider this API (endpoint) provides
+  # routing to the indvidual resource class's OmniAuthAPI callback endpoint.
+  # This API eventually gets mounted at /OMNIAUTH_PREFIX/ where OMNIAUTH prefix
+  # is configured in GrapeTokenAuth
+  class OmniAuthCallBackRouterAPI < Grape::API
+    helpers do
+      def redirect_route_from_api(api, provider)
+        prefix = api.routes.find do |r|
+          %r{/:provider/callback}.match(r.route_path)
+        end.route_path.split(%r{/:provider})[0]
+        Pathname.new(prefix).join(provider, 'callback.json').to_s
+      end
+
+      def resource_class_from_auth
+        scope = request.env.fetch('omniauth.params', {})['resource_class']
+        return unless scope
+        GrapeTokenAuth.configuration.scope_to_class(scope.underscore.to_sym)
+      end
+
+      def session
+        request.env['rack.session']
+      end
+    end
+    desc 'Callback endpoint that redirects to individual resource callbacks'
+    get ':provider/callback' do
+      # derive target api from 'resource_class' param, which was set
+      # before authentication.
+      resource_class = resource_class_from_auth
+      api = GrapeTokenAuth.const_get("#{resource_class}OmniAuthAPI") ||
+            OmniAuthAPI
+
+      # preserve omniauth info for success route. ignore 'extra' in twitter
+      session['gta.omniauth.auth'] = request.env['omniauth.auth']
+                                     .except('extra')
+      session['gta.omniauth.params'] = request.env['omniauth.params']
+
+      redirect redirect_route_from_api(api, params[:provider])
+    end
+
+    get '/failure' do
+      env['api.format'] = :html
+      content_type 'text/html; charset=utf-8'
+      OmniAuthFailureHTML.new(params[:message] || params['message']).render_html
+    end
+  end
+end