token_action 0.0.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2013 Open North Inc.
+
+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,143 @@
+# TokenAction
+
+[![Build Status](https://secure.travis-ci.org/opennorth/token_action.png)](http://travis-ci.org/opennorth/token_action)
+[![Dependency Status](https://gemnasium.com/opennorth/token_action.png)](https://gemnasium.com/opennorth/token_action)
+[![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/opennorth/token_action)
+
+TokenAction lets you create tokens to be used to authenticate actions. For example:
+
+* Create a token for a user to confirm an account
+* Create a token for a subscriber to unsubscribe from notifications
+* Create a token for a user to confirm a change of email address
+
+## Getting Started
+
+TokenAction works with Rails 3.1 onwards. Add it to your Gemfile:
+
+    gem 'token_action'
+
+Install the gem and configure your application to use TokenAction with:
+
+    bundle
+    bundle exec rails generate token_action
+
+If you are using ActiveRecord, run the migration:
+
+    bundle exec rake db:migrate
+
+## Basic Usage
+
+Create a shared secret to confirm a user account, for example:
+
+    token = TokenAction::Token.create! :kind => 'User', :args => [1, :confirm]
+    token.token # a 20-character alphanumeric string like "j7NtCaYfUpZXyDCseKG2"
+
+You can then send the token with instructions to the user via email. When the user visits `/tokens/j7NtCaYfUpZXyDCseKG2/confirm`, TokenAction will look up the token. If not found, it will log an informational message to the Rails logger, set `flash[:alert]` and redirect to the `root_path`. If found, it will call the `redeem_token` method on the `User` class, passing in the arguments `1` and `:confirm`. You must implement the public `redeem_token` method. For example:
+
+    class User < ActiveRecord::Base
+      def self.redeem_token(id, meth)
+        User.find(id).send(meth)
+      end
+
+      def confirm
+        update_attribute :confirmed, true
+      end
+    end
+
+If an exception is raised, TokenAction will log a warning message to the Rails logger, set `flash[:alert]` and redirect to the `root_path`. If no exception is raised, TokenAction will set `flash[:notice]` and redirect to the `root_path`. That's it!
+
+## Customization
+
+You can customize the redirect URLs, the routes, the flash messages and the tokens controller.
+
+### Redirect URLs
+
+To change the default success and failure URLs from `root_path`, edit the `config/initializers/token_action.rb` file created by `rails generate token_action`. You may also set success and failure URLs for each token, by creating tokens with `:success_url` and `:failure_url` arguments:
+
+    token = TokenAction::Token.create! :kind => 'Cat', :success_url => cat_path(1), :failure_url => '/oops'
+
+**Note:** If you change your URL structure after creating tokens, TokenAction may attempt to redirect to an unroutable path. If a path is unroutable, TokenAction will redirect to another URL in this order of precedence:
+
+* `Token#success_url`
+* `TokenAction.success_url`
+* `root_path`
+
+If an exception was raised and a path is unroutable, it will redirect in this order of precedence:
+
+* `Token#failure_url`
+* `TokenAction.failure_url`
+* `root_path`
+
+### Routes
+
+The TokenAction generator will add `mount TokenAction::Engine => '/token_action'` to your routes, which defines:
+
+    get 'tokens/:token/*path', :to => 'tokens#redeem'
+
+As such, you can write URLs like `tokens/xxx/confirm` or `tokens/xxx/unsubscribe` or `tokens/xxx/a/b/c`.
+
+To customize the first part of the route, replace `mount TokenAction::Engine => '/token_action'` with something like:
+
+    get 'jetons/:token/*path', :to => 'token_action/tokens#redeem'
+
+### Flash messages
+
+The TokenAction generator will create a `config/locales/token_action.en.yml` file with the default messages for when a token is not found, an exception is raised, or the action is performed successfully. You will probably want to change these messages depending on the action taken and the exception raised.
+
+* If a token was redeemed by accessing a URL like `tokens/xxx/confirm`, TokenAction will look for a message in the scope `token_action.tokens.confirm`. If not found, it will default to the scope `token_action.tokens.default`.
+
+* If a token was redeemed by accessing a long URL like `tokens/xxx/a/b/c`, TokenAction will look for a message in the scope `token_action.tokens.a.b.c`.
+
+You may want to raise an exception if an action has already been performed or if it is no longer valid, in which case you may want the failure message to change according to the exception raised.
+
+* If an `AlreadyConfirmed` exception is raised, TokenAction will look for a message in the scope `token_action.tokens.default.already_confirmed`. If not found, it will default to `token_action.tokens.default.failure`.
+
+* If a namespaced `MyModule::AlreadyConfirmed` exception is raised, TokenAction will look for a message in the scope `token_action.tokens.default.my_module.already_confirmed`.
+
+Putting it all together, if an `AlreadyConfirmed` exception is raised accessing a URL like `tokens/xxx/confirm`, TokenAction will look for messages in this order of preference:
+
+* `token_action.tokens.confirm.already_confirmed`
+* `token_action.tokens.default.already_confirmed`
+* `token_action.tokens.confirm.failure`
+* `token_action.tokens.default.failure`
+
+### Tokens controller
+
+To customize the controller without monkey patching, create a new controller like:
+
+    class TokensController < TokenAction::TokensController
+    end
+
+And replace the route with something like:
+
+    get 'tokens/:token/*path', :to => 'tokens#redeem'
+
+You can then override the `redeem` method in your new controller.
+
+## Supported ORMs
+
+* [ActiveRecord](https://rubygems.org/gems/activerecord)
+* [Mongoid](https://rubygems.org/gems/mongoid)
+
+It should be easy to add adapters for [MongoMapper](https://rubygems.org/gems/mongo_mapper), DataMapper, Sequel and CouchPotato. If you are using DataMapper or Sequel, you must use an ActiveModel compliance plugin:
+
+* [DataMapper plugin](https://github.com/datamapper/dm-active_model)
+* [Sequel plugin](http://sequel.rubyforge.org/rdoc-plugins/classes/Sequel/Plugins/ActiveModel.html)
+
+If using Sequel, you will want to use the [orm_adapter-sequel](https://github.com/elskwid/orm_adapter-sequel) gem. If using CouchPotato, you will need to write your own adapter for ORM Adapter.
+
+## Caveats
+
+* If you change the name of a class, update the `kind` attribute on its tokens to avoid making them unprocessable.
+* Be careful when changing the behavior of a `redeem_token` method, to avoid making tokens unprocessable.
+
+## Roadmap
+
+* The tokens controller only responds to HTML requests. Pull requests to add JSON and XML responders are welcome!
+* The generators do not have specs.
+
+## Bugs? Questions?
+
+This engine's main repository is on GitHub: [http://github.com/opennorth/token_action](http://github.com/opennorth/token_action), where your contributions, forks, bug reports, feature requests, and feedback are greatly welcomed.
+
+Copyright (c) 2012 Open North Inc., released under the MIT license

data/Rakefile

@@ -0,0 +1,16 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yard do
+    abort 'YARD is not available. In order to run yard, you must: gem install yard'
+  end
+end

data/app/controllers/token_action/application_controller.rb

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

data/app/controllers/token_action/tokens_controller.rb

@@ -0,0 +1,73 @@
+module TokenAction
+  class TokensController < ApplicationController
+    def redeem
+      @token = TokenAction::Token.to_adapter.find_first(:token => params[:token])
+      if @token
+        begin
+          # Do this in the controller's scope to allow access to request methods.
+          ActiveSupport::Inflector.constantize(@token.kind).redeem_token(*@token.args)
+          redirect_to success_url, :notice => translate(:success)
+        rescue => e
+          key = ActiveSupport::Inflector.underscore(e.class).gsub('/', I18n.default_separator)
+          logger.warn "TokenAction failed to perform the action for the token '#{params[:token]}': #{e.message}"
+          redirect_to failure_url, :alert => translate(key, :failure)
+        end
+      else
+        logger.info "TokenAction failed to find the token '#{params[:token]}'"
+        redirect_to failure_url, :alert => translate(:not_found)
+      end
+    end
+
+  private
+
+    # Returns a translation.
+    #
+    # @param [Array] args translation keys
+    # @return [String] a translation
+    def translate(*args)
+      path = params[:path].gsub('/', I18n.default_separator)
+      keys = []
+
+      # Respect the order of precedence described in the readme.
+      args.each do |key|
+        [path, :default].each do |scope|
+          keys << [:token_action, :tokens, scope, key]
+        end
+      end
+      keys.map! do |key|
+        key.join(I18n.default_separator).to_sym
+      end
+
+      key, *default = *keys
+      I18n.translate(key, :default => default)
+    end
+
+    # Returns the success URL.
+    #
+    # @return [String] a URL
+    def success_url
+      [@token && @token.success_url, TokenAction.success_url].find do |url|
+        url.present? && routable?(url)
+      end || main_app.root_path
+    end
+
+    # Returns the failure URL.
+    #
+    # @return [String] a URL
+    def failure_url
+      [@token && @token.failure_url, TokenAction.failure_url].find do |url|
+        url.present? && routable?(url)
+      end || main_app.root_path
+    end
+
+    # Returns whether a path is routable.
+    #
+    # @param [String] path a path
+    # @return [Boolean] whether the path is routable
+    def routable?(path)
+      !!Rails.application.routes.recognize_path(path, :method => :get)
+    rescue ActionController::RoutingError
+      false
+    end
+  end
+end

data/config/locales/en.yml

@@ -0,0 +1,10 @@
+en:
+  token_action:
+    tokens:
+      default:
+        # If the token is found and no exception is raised.
+        success: Your request was successfully processed.
+        # If the token is found and an exception is raised.
+        failure: An error occurred while processing your request.
+        # If the token cannot be found.
+        not_found: Sorry, your request could not be processed.

data/config/routes.rb

@@ -0,0 +1,3 @@
+TokenAction::Engine.routes.draw do
+  get 'tokens/:token/*path', :to => 'tokens#redeem'
+end

data/lib/generators/active_record/templates/migration.rb

@@ -0,0 +1,15 @@
+class CreateTokenActionTokens < ActiveRecord::Migration
+  def change
+    create_table(:token_action_tokens) do |t|
+      t.string :token
+      t.string :kind
+      t.text :args
+      t.string :success_url
+      t.string :failure_url
+
+      t.timestamps
+    end
+
+    add_index :token_action_tokens, :token, :unique => true
+  end
+end

data/lib/generators/active_record/token_action_generator.rb

@@ -0,0 +1,25 @@
+require 'rails/generators/active_record'
+
+module ActiveRecord
+  module Generators
+    # This generator will run during `rails generate token_action`.
+    #
+    # @see ActiveRecord::Generators::DeviseGenerator
+    # @see Devise::Generators::OrmHelpers
+    class TokenActionGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('../templates', __FILE__)
+
+      def copy_migration_file
+        migration_template 'migration.rb', 'db/migrate/create_token_action_tokens'
+      end
+
+    private
+
+      def self.next_migration_number(number)
+        ActiveRecord::Generators::Base.next_migration_number(number)
+      end
+    end
+  end
+end

data/lib/generators/mongoid/token_action_generator.rb

@@ -0,0 +1,7 @@
+module Mongoid
+  module Generators
+    class TokenActionGenerator < Rails::Generators::Base
+      # Do nothing. Avoids error during generation.
+    end
+  end
+end

data/lib/generators/templates/README

@@ -0,0 +1,10 @@
+To complete the installation of TokenAction:
+
+  1. Define a root route in config/routes.rb. For example:
+
+       root :to => 'home#index'
+
+  2. Add flash messages to app/views/layouts/application.html.erb. For example:
+
+       <p class="alert alert-success"><%= notice %></p>
+       <p class="alert alert-error"><%= alert %></p>

data/lib/generators/templates/token_action.rb

@@ -0,0 +1,25 @@
+TokenAction.setup do |config|
+  # Load and configure the ORM. Supports "active_record" and "mongoid". You
+  # should not require more than one ORM for TokenAction.
+  require 'token_action/orm/<%= options[:orm] %>'
+
+  # If not overridden on a per-token basis, TokenAction will redirect to this
+  # URL after performing an action successfully. If not set, it will redirect to
+  # your application's root_path. Set it with:
+  #
+  # config.success_url = 'custom/redirect/url'
+  #
+  # If using a URL helper, wrap the helper in a lambda or proc:
+  #
+  # config.success_url = lambda { Rails.application.routes.url_helpers.root_url }
+
+  # If not overridden on a per-token basis, TokenAction will redirect to this
+  # URL when an exception is raised while performing an action, or when a token
+  # cannot be found. If not set, it will redirect to your app's root_path.
+  #
+  # config.failure_url = 'custom/redirect/url'
+  #
+  # If using a URL helper, wrap the helper in a lambda or proc:
+  #
+  # config.failure_url = lambda { Rails.application.routes.url_helpers.root_url }
+end

data/lib/generators/token_action_generator.rb

@@ -0,0 +1,35 @@
+module TokenAction
+  module Generators
+    # Run this generator once before using TokenAction in your application.
+    #
+    # @example
+    #   rails generate token_action
+    #
+    # @see Devise::Generators::InstallGenerator
+    # @see Devise::Generators::DeviseGenerator
+    class TokenActionGenerator < Rails::Generators::Base
+      desc "Copies TokenAction's initializer and locale files, adds routes, " <<
+        "and creates an ActiveRecord migration file if necessary."
+
+      hook_for :orm
+      namespace 'token_action'
+      source_root File.expand_path('../templates', __FILE__)
+
+      def copy_initializer_file
+        template 'token_action.rb', 'config/initializers/token_action.rb'
+      end
+
+      def copy_locale_file
+        copy_file '../../../config/locales/en.yml', 'config/locales/token_action.en.yml'
+      end
+
+      def add_routes
+        route "mount TokenAction::Engine => '/token_action'"
+      end
+
+      def show_readme
+        readme 'README' if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/token_action/engine.rb

@@ -0,0 +1,5 @@
+module TokenAction
+  class Engine < ::Rails::Engine
+    isolate_namespace TokenAction
+  end
+end

data/lib/token_action/mixins/model.rb

@@ -0,0 +1,24 @@
+module TokenAction
+  module Model
+    extend ActiveSupport::Concern
+    include TokenAction::TokenGenerator
+
+    included do
+      validates_presence_of :token, :kind
+
+      # ActiveRecord, Mongoid, MongoMapper and DataMapper implement
+      # `validates_uniqueness_of`. Sequel implements it in a plugin.
+      #
+      # @see http://sequel.rubyforge.org/rdoc-plugins/classes/Sequel/Plugins/ValidationClassMethods.html
+      validates_uniqueness_of :token
+
+      before_validation :set_token
+    end
+
+  private
+
+    def set_token
+      self.token ||= self.class.generate_token(:token)
+    end
+  end
+end

data/lib/token_action/mixins/token_generator.rb

@@ -0,0 +1,19 @@
+module TokenAction
+  module TokenGenerator
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      # Returns a new alphanumeric token.
+      #
+      # @param [String,Symbol] column an attribute
+      # @return [String] a random alphanumeric string
+      # @see Devise::Models::Authenticatable::ClassMethods
+      def generate_token(column)
+        loop do
+          token = TokenAction.friendly_token
+          break token unless to_adapter.find_first({ column => token })
+        end
+      end
+    end
+  end
+end