simple_token_authentication 1.5.1 → 1.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4aa1abbb8d50757dcf03bc2258df433e83f0e6fa
-  data.tar.gz: a1e59e796dc712d0915f960e94ed6291226a0513
+  metadata.gz: 6e7a77a49ad9d0cecdf975b21c733087091a4671
+  data.tar.gz: 6ea3dea47399dc595603ebbe97bc859417bfe775
 SHA512:
-  metadata.gz: 2a991fdfebff8510b53bdb51a8c3c7eb50768568307977104225506d598d7cf05164da64fcb362851b44038a8f97c350c2b0adc31fd833a1a4ff1adbbea2140c
-  data.tar.gz: 2f02cb5a9bc457ecde73c588fae28c8e3235f352cb140a2cb64beff25ad18662ea56d613d49bb6fe480fd5303765fef68fb9828fdcd8180d48890aaff757ac27
+  metadata.gz: c8f34f63afbf988faccb9d952740ef54283846e1d9163d937323102e793948bed2567fd0cacca4c311cb6243d97b42223874045fad0f39b611d3e7bf29e889eb
+  data.tar.gz: 9409b4492ef48a1ceb2f3c4ed00a509e37cf0b9de0338486474fb5101c4eccb685eb09017d0a215944c6cafe453eeea9bb4bde06e1ec9bae5cc5f834437abdf0

data/README.md

@@ -1,10 +1,12 @@
 Simple Token Authentication
 ===========================
 
-[![Gem Version](https://badge.fury.io/rb/simple_token_authentication.png)](http://badge.fury.io/rb/simple_token_authentication)
-[![Build Status](https://travis-ci.org/gonzalo-bulnes/simple_token_authentication.png?branch=master)](https://travis-ci.org/gonzalo-bulnes/simple_token_authentication)
-[![Code Climate](https://codeclimate.com/github/gonzalo-bulnes/simple_token_authentication.png)](https://codeclimate.com/github/gonzalo-bulnes/simple_token_authentication)
+[![Gem Version](https://badge.fury.io/rb/simple_token_authentication.svg)](http://badge.fury.io/rb/simple_token_authentication)
+[![Build Status](https://travis-ci.org/gonzalo-bulnes/simple_token_authentication.svg?branch=master)](https://travis-ci.org/gonzalo-bulnes/simple_token_authentication)
+[![Code Climate](https://codeclimate.com/github/gonzalo-bulnes/simple_token_authentication.svg)](https://codeclimate.com/github/gonzalo-bulnes/simple_token_authentication)
 [![Dependency Status](https://gemnasium.com/gonzalo-bulnes/simple_token_authentication.svg)](https://gemnasium.com/gonzalo-bulnes/simple_token_authentication)
+[![security](https://hakiri.io/github/gonzalo-bulnes/simple_token_authentication/master.svg)](https://hakiri.io/github/gonzalo-bulnes/simple_token_authentication/master)
+[![Inline docs](http://inch-ci.org/github/gonzalo-bulnes/simple_token_authentication.svg?branch=master)](http://inch-ci.org/github/gonzalo-bulnes/simple_token_authentication)
 
 Token authentication support has been removed from [Devise][devise] for security reasons. In [this gist][original-gist], Devise's [José Valim][josevalim] explains how token authentication should be performed in order to remain safe.
 
@@ -170,19 +172,6 @@ If sign-in is successful, no other authentication method will be run, but if it
 Documentation
 -------------
 
-### Executable documentation
-
-The Cucumber scenarii describe how to setup demonstration applications for different use cases. While you can read the `rake` output, you may prefer to read it in HTML format: see `doc/features.html`. The file is generated automatically by Cucumber, if necessary, you can update it by yourself:
-
-```bash
-cd simple_token_authentication
-rake features_html # generate the features documentation
-
-# Open doc/features.html in your preferred web browser.
-```
-
-I find that HTML output quite enjoyable, I hope you'll do so!
-
 ### Frequently Asked Questions
 
 Any question? Please don't hesitate to open a new issue to get help. I keep questions tagged to make possible to [review the open questions][open-questions], while closed questions are organized as a sort of [FAQ][faq].
@@ -199,18 +188,23 @@ Releases are commented to provide a brief [changelog][changelog].
 Development
 -----------
 
-### Testing
+### Testing and documentation
 
-Since `v1.0.0`, this gem development is test-driven. Each use case should be described with [RSpec][rspec] within an example app. That app will be created and configured automatically by [Aruba][aruba] as a [Cucumber][cucumber] feature.
+This gem development has been test-driven since `v1.0.0`. Until `v1.5.1`, the gem behaviour was described using [Cucumber][cucumber] and [RSpec][rspec] in a dummy app generated by [Aruba][aruba]. Since `v1.5.2` it is described using Rspec alone.
 
-The resulting Cucumber features are a bit verbose, and their output when errors occur is not ideal, but their output when they are passing, on the contrary, provides an easy-to-reproduce recipe to build the example app (see [Executable documentation][exec-doc]). I find that useful enough to be patient with red scenarii for now.
+RSpec [tags][tags] are used to categorize the spec examples.
+
+Spec examples that are tagged as `public` describe aspects of the gem public API, and MAY be considered as the gem documentation.
+
+The `private` or `protected` specs are written for development purpose only. Because they describe internal behaviour which may change at any moment without notice, they are only executed as a secondary task by the [continuous integration service][travis] and SHOULD be ignored.
+
+Run `rake spec:public` to print the gem public documentation.
 
   [aruba]: https://github.com/cucumber/aruba
   [cucumber]: https://github.com/cucumber/cucumber-rails
   [rspec]: https://www.relishapp.com/rspec/rspec-rails/docs
-  [exec-doc]: https://github.com/gonzalo-bulnes/simple_token_authentication#executable-documentation
-
-You can run the full test suite with `cd simple_token_authentication && rake`.
+  [tags]: https://www.relishapp.com/rspec/rspec-core/v/3-1/docs/command-line/tag-option
+  [travis]: https://travis-ci.org/gonzalo-bulnes/simple_token_authentication/builds
 
 ### Contributions
 
@@ -218,16 +212,21 @@ Contributions are welcome! I'm not personally maintaining any [list of contribut
 
   [contributors]: https://github.com/gonzalo-bulnes/simple_token_authentication/graphs/contributors
 
+Please be sure to [review the open issues][open-questions] and contribute with your ideas or code in the issue best suited to the topic. Keeping discussions in a single place makes easier to everyone interested in that topic to keep track of the contributions.
+
 Credits
 -------
 
-It may sound a bit redundant, but this gem wouldn't exist without [this gist][original-gist].
+It may sound a bit redundant, but this gem wouldn't exist without [this gist][original-gist], nor without the [comments][issues] and [contributions][pulls] of many people. Thank them if you see them!
+
+  [issues]: https://github.com/gonzalo-bulnes/simple_token_authentication/issues
+  [pulls]: https://github.com/gonzalo-bulnes/simple_token_authentication/pulls
 
 License
 -------
 
     Simple Token Authentication
-    Copyright (C) 2013 Gonzalo Bulnes Guilpain
+    Copyright (C) 2013, 2014 Gonzalo Bulnes Guilpain
 
     This program is free software: you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by

data/Rakefile

@@ -19,23 +19,43 @@ Bundler::GemHelper.install_tasks
 
 
 begin
-  require 'cucumber'
-  require 'cucumber/rake/task'
+  require 'inch/rake'
 
-  Cucumber::Rake::Task.new(:features) do |t|
-    t.cucumber_opts = "--format pretty"
+  Inch::Rake::Suggest.new(:inch) do |suggest|
+    suggest.args << "--private"
+    suggest.args << "--pedantic"
   end
+rescue LoadError
+  desc 'Inch rake task not available'
+  task :inch do
+  abort 'Inch rake task is not available. Be sure to install inch as a gem or plugin'
+  end
+end
+
+begin
+  require 'rspec/core/rake_task'
+
+  desc 'Provide private interfaces documentation'
+  RSpec::Core::RakeTask.new(:spec)
 
-  Cucumber::Rake::Task.new(:features_html) do |t|
-    t.cucumber_opts = "--format html --out doc/features.html"
+  namespace :spec do
+    desc 'Provide public interfaces documentation'
+    RSpec::Core::RakeTask.new(:public) do |t|
+      t.rspec_opts = "--tag public"
+    end
   end
 
+  namespace :spec do
+    desc 'Provide private interfaces documentation for development purpose'
+    RSpec::Core::RakeTask.new(:development) do |t|
+      t.rspec_opts = "--tag protected --tag private"
+    end
+  end
 rescue LoadError
-  desc 'Cucumber rake task not available'
-  task :features do
-    abort 'Cucumber rake task is not available. Be sure to install cucumber as a gem or plugin'
+  desc 'RSpec rake task not available'
+  task :spec do
+  abort 'RSpec rake task is not available. Be sure to install rspec-core as a gem or plugin'
   end
 end
 
-
-task default: :features
+task default: ['spec:public', 'spec:development', :inch]

data/doc/README.md

@@ -0,0 +1,18 @@
+Documentation
+=============
+
+**Looking for the HTML features decription?**
+
+The Cucumber features that documented the gem behaviour until `v1.5.1` constituted a robust tests suite, but they were slow and writting them was difficult enough to become a continuous bottleneck.
+
+I decided to tackle the issue by replacing most scenarios by unit tests (see [#104][issue]), and since `v1.5.2` the gem behaviour is documented using RSpec only.
+
+I liked the [executable documentation][exec-doc] idea, and I do not discard using Cucumber again to test _Simple Token Authentication_.
+However, truth is that neither the somewhat intricated [Cucumber][cucumber] - [Aruba][aruba] - [RSpec][rspec] setup or the steps I wrote were exemplary enough to make justice to the great tool Cucumber is. So I decided to stop maintaining  the features and to remove them. The RSpec test suite provides a nice [documentation][doc], and sometimes the best is a fresh start.
+
+  [exec-doc]: https://github.com/gonzalo-bulnes/simple_token_authentication/tree/v1.5.1#executable-documentation
+  [doc]: #testing-and-documentation
+  [issue]: https://github.com/gonzalo-bulnes/simple_token_authentication/issues/104
+  [aruba]: https://github.com/cucumber/aruba
+  [cucumber]: https://github.com/cucumber/cucumber-rails
+  [rspec]: https://www.relishapp.com/rspec/rspec-rails/docs

data/lib/simple_token_authentication.rb

@@ -4,4 +4,43 @@ require 'simple_token_authentication/configuration'
 
 module SimpleTokenAuthentication
   extend Configuration
+
+  private
+
+  def self.ensure_models_can_act_as_token_authenticatables model_adapters
+    model_adapters.each do |model_adapter|
+      model_adapter.base_class.send :include, SimpleTokenAuthentication::ActsAsTokenAuthenticatable
+    end
+  end
+
+  def self.ensure_controllers_can_act_as_token_authentication_handlers controller_adapters
+    controller_adapters.each do |controller_adapter|
+      controller_adapter.base_class.send :extend, SimpleTokenAuthentication::ActsAsTokenAuthenticationHandler
+    end
+  end
+
+  # Private: Load the available adapters.
+  #
+  # adapters_short_names - Array of names of the adapters to load if available
+  #
+  # Example
+  #
+  #    load_available_adapters ['unavailable_adapter', 'available_adapter']
+  #    # => [SimpleTokenAuthentication::Adapters::AvailableAdapter]
+  #
+  # Returns an Array of available adapters
+  def self.load_available_adapters adapters_short_names
+    adapters_short_names.collect do |short_name|
+      adapter_name = "simple_token_authentication/adapters/#{short_name}_adapter"
+      if require adapter_name
+        adapter_name.camelize.constantize
+      end
+    end
+  end
+
+  available_model_adapters = load_available_adapters SimpleTokenAuthentication.model_adapters
+  ensure_models_can_act_as_token_authenticatables available_model_adapters
+
+  available_controller_adapters = load_available_adapters SimpleTokenAuthentication.controller_adapters
+  ensure_controllers_can_act_as_token_authentication_handlers available_controller_adapters
 end

data/lib/simple_token_authentication/acts_as_token_authenticatable.rb

@@ -1,33 +1,44 @@
+require 'active_support/concern'
+require 'simple_token_authentication/token_generator'
+
 module SimpleTokenAuthentication
   module ActsAsTokenAuthenticatable
-    extend ActiveSupport::Concern
+    extend ::ActiveSupport::Concern
 
     # Please see https://gist.github.com/josevalim/fb706b1e933ef01e4fb6
     # before editing this file, the discussion is very interesting.
 
     included do
       private :generate_authentication_token
+      private :token_suitable?
+      private :token_generator
     end
 
     def ensure_authentication_token
       if authentication_token.blank?
-        self.authentication_token = generate_authentication_token
+        self.authentication_token = generate_authentication_token(token_generator)
       end
     end
 
-    def generate_authentication_token
+    def generate_authentication_token(token_generator)
       loop do
-        token = Devise.friendly_token
-        break token unless self.class.exists?(authentication_token: token)
+        token = token_generator.generate_token
+        break token if token_suitable?(token)
       end
     end
 
+    def token_suitable?(token)
+      not self.class.exists?(authentication_token: token)
+    end
+
+    def token_generator
+      @token_generator ||= TokenGenerator.new
+    end
+
     module ClassMethods
       def acts_as_token_authenticatable(options = {})
-        include SimpleTokenAuthentication::ActsAsTokenAuthenticatable
         before_save :ensure_authentication_token
       end
     end
   end
 end
-ActiveRecord::Base.send :include, SimpleTokenAuthentication::ActsAsTokenAuthenticatable

data/lib/simple_token_authentication/acts_as_token_authentication_handler.rb

@@ -1,133 +1,22 @@
-module SimpleTokenAuthentication
-  module ActsAsTokenAuthenticationHandlerMethods
-    extend ActiveSupport::Concern
-
-    # Please see https://gist.github.com/josevalim/fb706b1e933ef01e4fb6
-    # before editing this file, the discussion is very interesting.
-
-    included do
-      private :authenticate_entity_from_token!
-      private :header_token_name
-      private :header_email_name
-
-      # This is necessary to test which arguments were passed to sign_in
-      # from authenticate_entity_from_token!
-      # See https://github.com/gonzalo-bulnes/simple_token_authentication/pull/32
-      ActionController::Base.send :include, Devise::Controllers::SignInOut if Rails.env.test?
-    end
-
-    def authenticate_entity!(entity_class)
-      # Caution: entity should be a singular camel-cased name but could be pluralized or underscored.
-      self.method("authenticate_#{entity_class.name.singularize.underscore}!".to_sym).call
-    end
-
-
-    # For this example, we are simply using token authentication
-    # via parameters. However, anyone could use Rails's token
-    # authentication features to get the token from a header.
-    def authenticate_entity_from_token!(entity_class)
-      # Set the authentication token params if not already present,
-      # see http://stackoverflow.com/questions/11017348/rails-api-authentication-by-headers-token
-      params_token_name = "#{entity_class.name.singularize.underscore}_token".to_sym
-      params_email_name = "#{entity_class.name.singularize.underscore}_email".to_sym
-      if token = params[params_token_name].blank? && request.headers[header_token_name(entity_class)]
-        params[params_token_name] = token
-      end
-      if email = params[params_email_name].blank? && request.headers[header_email_name(entity_class)]
-        params[params_email_name] = email
-      end
-
-      email = params[params_email_name].presence
-      # See https://github.com/ryanb/cancan/blob/1.6.10/lib/cancan/controller_resource.rb#L108-L111
-      entity = nil
-      if entity_class.respond_to? "find_by"
-        entity = email && entity_class.find_by(email: email)
-      elsif entity_class.respond_to? "find_by_email"
-        entity = email && entity_class.find_by_email(email)
-      end
-
-      # Notice how we use Devise.secure_compare to compare the token
-      # in the database with the token given in the params, mitigating
-      # timing attacks.
-      if entity && Devise.secure_compare(entity.authentication_token, params[params_token_name])
-        # Sign in using token should not be tracked by Devise trackable
-        # See https://github.com/plataformatec/devise/issues/953
-        env["devise.skip_trackable"] = true
-
-        # Notice the store option defaults to false, so the entity
-        # is not actually stored in the session and a token is needed
-        # for every request. That behaviour can be configured through
-        # the sign_in_token option.
-        sign_in entity, store: SimpleTokenAuthentication.sign_in_token
-      end
-    end
-
-    # Private: Return the name of the header to watch for the token authentication param
-    def header_token_name(entity_class)
-      if SimpleTokenAuthentication.header_names["#{entity_class.name.singularize.underscore}".to_sym].presence
-        SimpleTokenAuthentication.header_names["#{entity_class.name.singularize.underscore}".to_sym][:authentication_token]
-      else
-        "X-#{entity_class.name.singularize.camelize}-Token"
-      end
-    end
-
-    # Private: Return the name of the header to watch for the email param
-    def header_email_name(entity_class)
-      if SimpleTokenAuthentication.header_names["#{entity_class.name.singularize.underscore}".to_sym].presence
-        SimpleTokenAuthentication.header_names["#{entity_class.name.singularize.underscore}".to_sym][:email]
-      else
-        "X-#{entity_class.name.singularize.camelize}-Email"
-      end
-    end
-  end
+require 'active_support/deprecation'
+require 'simple_token_authentication/token_authentication_handler'
 
+module SimpleTokenAuthentication
   module ActsAsTokenAuthenticationHandler
-    extend ActiveSupport::Concern
 
-    # I have insulated the methods into an additional module to avoid before_filters
-    # to be applied by the `included` block before acts_as_token_authentication_handler_for was called.
+    # This module ensures that no TokenAuthenticationHandler behaviour
+    # is added before the class actually `acts_as_token_authentication_handler_for`
+    # some token authenticatable model.
     # See https://github.com/gonzalo-bulnes/simple_token_authentication/issues/8#issuecomment-31707201
 
-    included do
-      # nop
+    def acts_as_token_authentication_handler_for(model, options = {})
+      include SimpleTokenAuthentication::TokenAuthenticationHandler
+      handle_token_authentication_for(model, options)
     end
 
-    module ClassMethods
-      def acts_as_token_authentication_handler_for(entity, options = {})
-        options = { fallback_to_devise: true }.merge(options)
-
-        include SimpleTokenAuthentication::ActsAsTokenAuthenticationHandlerMethods
-
-        define_acts_as_token_authentication_helpers_for(entity)
-
-        authenticate_method = if options[:fallback_to_devise]
-          :"authenticate_#{entity.name.singularize.underscore}_from_token!"
-        else
-          :"authenticate_#{entity.name.singularize.underscore}_from_token"
-        end
-        before_filter authenticate_method, options.slice(:only, :except)
-      end
-
-      def acts_as_token_authentication_handler
-        ActiveSupport::Deprecation.warn "`acts_as_token_authentication_handler()` is deprecated and may be removed from future releases, use `acts_as_token_authentication_handler_for(User)` instead.", caller
-        acts_as_token_authentication_handler_for User
-      end
-
-      def define_acts_as_token_authentication_helpers_for(entity_class)
-        entity_underscored = entity_class.name.singularize.underscore
-
-        class_eval <<-METHODS, __FILE__, __LINE__ + 1
-          def authenticate_#{entity_underscored}_from_token
-            authenticate_entity_from_token!(#{entity_class.name})
-          end
-
-          def authenticate_#{entity_underscored}_from_token!
-            authenticate_entity_from_token!(#{entity_class.name})
-            authenticate_entity!(#{entity_class.name})
-          end
-        METHODS
-      end
+    def acts_as_token_authentication_handler
+      ::ActiveSupport::Deprecation.warn "`acts_as_token_authentication_handler()` is deprecated and may be removed from future releases, use `acts_as_token_authentication_handler_for(User)` instead.", caller
+      acts_as_token_authentication_handler_for User
     end
   end
 end
-ActionController::Base.send :include, SimpleTokenAuthentication::ActsAsTokenAuthenticationHandler

data/lib/simple_token_authentication/adapter.rb

@@ -0,0 +1,7 @@
+module SimpleTokenAuthentication
+  module Adapter
+    def base_class
+      raise NotImplementedError
+    end
+  end
+end

data/lib/simple_token_authentication/adapters/active_record_adapter.rb

@@ -0,0 +1,14 @@
+require 'active_record'
+require 'simple_token_authentication/adapter'
+
+module SimpleTokenAuthentication
+  module Adapters
+    class ActiveRecordAdapter
+      extend SimpleTokenAuthentication::Adapter
+
+      def self.base_class
+        ::ActiveRecord::Base
+      end
+    end
+  end
+end

data/lib/simple_token_authentication/adapters/rails_adapter.rb

@@ -0,0 +1,14 @@
+require 'action_controller'
+require 'simple_token_authentication/adapter'
+
+module SimpleTokenAuthentication
+  module Adapters
+    class RailsAdapter
+      extend SimpleTokenAuthentication::Adapter
+
+      def self.base_class
+        ::ActionController::Base
+      end
+    end
+  end
+end