warden-github-rails 0.0.1

data/.gitignore

@@ -0,0 +1,20 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+tags
+bin/
+log

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+script: "bundle exec rspec"
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - ruby-head
+matrix:
+  allow_failures:
+    - rvm: ruby-head

data/Gemfile

@@ -0,0 +1,14 @@
+source 'https://rubygems.org'
+
+gemspec
+
+if ENV['EDGE']
+  gem 'warden-github', :github => 'atmos/warden-github'
+end
+
+group :development do
+  unless ENV['CI']
+    gem 'debugger',   :platforms => :ruby_19, :require => false
+    gem 'ruby-debug', :platforms => :ruby_18, :require => false
+  end
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Philipe Fatio
+
+MIT License
+
+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,188 @@
+# warden-github-rails
+
+[![Build Status](https://travis-ci.org/fphilipe/warden-github-rails.png)](https://travis-ci.org/fphilipe/warden-github-rails)
+[![Gem Version](https://badge.fury.io/rb/warden-github-rails.png)](http://badge.fury.io/rb/warden-github-rails)
+[![Dependency Status](https://gemnasium.com/fphilipe/warden-github-rails.png)](https://gemnasium.com/fphilipe/warden-github-rails)
+[![Code Climate](https://codeclimate.com/github/fphilipe/warden-github-rails.png)](https://codeclimate.com/github/fphilipe/warden-github-rails)
+
+A gem for rails that provides easy GitHub OAuth integration.
+It is built on top of [warden-github](https://github.com/atmos/warden-github), which gives you an easy to use [warden](https://github.com/hassox/warden) strategy to authenticate GitHub users.
+
+## Motivation
+
+**Wouldn't it be nice to**
+
+- use your organization and it's teams for user access control?
+- add a new employee to your GitHub organization or team in order to grant them access to your app's admin area?
+
+The motivation for this gem was to provide a very easy authorization (not authentication) mechanism to existing rails apps for admins, especially in combination with organization and team memberships.
+The provided routing helpers do exactly that.
+They allow you to restrict access to members of your organization or a certain team.
+
+This is how your rails `routes.rb` could look like:
+
+```ruby
+constraints(:subdomain => 'admin') do
+  github_authenticate(:org => 'my_company_inc') do
+    resources :users
+    resources :projects
+
+    github_authenticated(:team => 'sysadmins') do
+      resource :infrastructure
+    end
+  end
+end
+```
+
+Of course, this gem can also be used for user registration and authentication.
+Several helper methods are available in the controller to accomplish this:
+
+```ruby
+class UsersController < ApplicationController
+  # ...
+
+  def new
+    github_authenticate! # Performs OAuth flow when not logged in.
+    @user = User.new(:name => github_user.name, :email => github_user.email)
+  end
+
+  def create
+    attrs = params.require(:user).permit(:name, :email).merge(:github_id => github_user.id)
+    @user = User.create(attrs)
+
+    if @user
+      redirect_to :show
+    else
+      render :new
+    end
+  end
+
+  # ...
+end
+```
+
+## Usage
+
+### Configuration
+
+First off, you might want to configure this gem by creating an initializer such as `config/initializers/warden_github_rails.rb`.
+There you can define:
+
+- various scopes and their configs (scopes are types of users with different configs)
+- the default scope (which is `:user` by default)
+- team aliases (GitHub teams are identified by a numerical ID; defining an alias for a team makes it easier to use)
+
+Here's how such a config might look like:
+
+```ruby
+Warden::GitHub::Rails.setup do |config|
+  config.add_scope :user,  :client_id     => 'foo',
+                           :client_secret => 'bar',
+                           :scope         => 'user'
+
+  config.add_scope :admin, :client_id     => 'abc',
+                           :client_secret => 'xyz',
+                           :redirect_uri  => '/admin/login/callback',
+                           :scope         => 'repo'
+
+  config.default_scope = :admin
+
+  config.add_team :marketing, 456
+end
+```
+
+For a list of allowed config parameters to use in `#add_scope`, read the [warden-github documentation](https://github.com/atmos/warden-github#parameters).
+
+### Inside `routes.rb`
+
+The available routing helpers are defined and documented in [lib/warden/github/rails/routes.rb](lib/warden/github/rails/routes.rb).
+They all accept an optional scope that, when omitted, falls back to the default_scope configured in the initializer.
+
+Examples:
+
+```ruby
+# Performs login if not logged in already.
+github_authenticate do
+  resource :profile
+end
+
+# Does not perform login when not logged in.
+github_authenticated do
+  delete '/logout' => 'sessions#delete'
+end
+
+# Only matches when not logged in. Does not perform login.
+github_unauthenticated do
+  resource :registration
+end
+
+# Only matches when member of the organization. Initiates login if not logged in.
+github_authenticate(:org => 'my_company') do
+  resource :admin
+end
+
+# Only matches when member of the team. Does not initiate login if not logged in.
+github_authenticated(:team => 'markting') do
+  get '/dashboard' => 'dashboard#show'
+end
+
+# Using dynamic membership values:
+github_authenticate(:org => lambda { |req| r.params[:id] }) do
+  get '/orgs/:id' => 'orgs#show'
+end
+```
+
+### Inside a Controller
+
+The available controller helpers are defined and documented in [lib/warden/github/rails/controller_helpers.rb](lib/warden/github/rails/controller_helpers.rb).
+They all accept an optional scope that, when omitted, falls back to the default_scope configured in the initializer.
+
+```ruby
+class SomeController < ActionController::Base
+  def show
+    @is_admin = github_authenticated?(:admin)
+  end
+
+  def delete
+    github_logout
+    redirect_to '/'
+  end
+
+  def settings
+    github_authenticate!
+    @settings = UserSettings.find_by_github_user_id(github_user.id)
+  end
+
+  def finish_wizard
+    github_session[:wizard_completed] = true
+  end
+
+  def followers
+    @followers = github_user.api.followers
+  end
+end
+```
+
+### Communicating with the GitHub API
+
+Once a user is logged in, you'll have access to it in the controller using `github_user`. It is an instance of `Warden::GitHub::User` which is defined in the [warden-github](https://github.com/atmos/warden-github/blob/master/lib/warden/github/user.rb) gem. The instance has several methods to access user information such as `#name`, `#id`, `#email`, etc. It also features a method `#api` which returns a preconfigured [Octokit](https://github.com/pengwynn/octokit) client for that user.
+
+## Known Limitations
+
+Currently, this gem does not play nicely with [Devise](https://github.com/plataformatec/devise). Devise is built on top of warden and performs some monkeypatching of warden which breaks this gem. Support will be added as soon as possible.
+
+## Additional Information
+
+### Dependencies
+
+- [warden-github](https://github.com/atmos/warden-github)
+    - [warden](https://github.com/hassox/warden)
+    - [octokit](https://github.com/pengwynn/octokit)
+
+### Maintainers
+
+- Philipe Fatio ([@fphilipe](https://github.com/fphilipe))
+
+### License
+
+MIT License. Copyright 2013 Philipe Fatio

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/lib/warden/github/rails.rb

@@ -0,0 +1,42 @@
+require 'warden/github'
+
+require 'warden/github/rails/version'
+require 'warden/github/rails/routes'
+require 'warden/github/rails/railtie'
+require 'warden/github/rails/config'
+require 'warden/github/rails/controller_helpers'
+require 'warden/github/rails/view_helpers'
+
+require 'forwardable'
+
+module Warden
+  module GitHub
+    module Rails
+      extend SingleForwardable
+
+      def_delegators :config,
+                     :default_scope,
+                     :warden_config,
+                     :warden_config=,
+                     :scopes,
+                     :team_id
+
+      @config = Config.new
+
+      def self.config
+        @config
+      end
+
+      # Use this method to setup this gem.
+      #
+      # @example
+      #
+      #   Warden::GitHub::Rails.setup do |config|
+      #     # ...
+      #   end
+      def self.setup
+        yield config
+      end
+    end
+  end
+end

data/lib/warden/github/rails/config.rb

@@ -0,0 +1,52 @@
+module Warden
+  module GitHub
+    module Rails
+      class Config
+        BadConfig = Class.new(StandardError)
+
+        # A cache of the warden config for the active manager.
+        attr_accessor :warden_config
+
+        # Default scope to use when not explicitly specified.
+        attr_accessor :default_scope
+
+        # The list of scopes and their configs. This is used to add custom
+        # configs to a specific scope. When using a scope that is not listed
+        # here, it will use the default configs from warden-github.
+        attr_reader :scopes
+
+        # A hash containing team alias names and their numeric id.
+        attr_reader :teams
+
+        def initialize
+          @default_scope = :user
+          @scopes = {}
+          @teams = {}
+        end
+
+        # Adds a scope with custom configurations to the list of scopes.
+        def add_scope(name, config={})
+          scopes[name] = config
+        end
+
+        # Maps a team id to a name in order to easier reference it.
+        def add_team(name, id)
+          teams[name.to_sym] = Integer(id)
+        end
+
+        # Gets the team id for a team id or alias.
+        def team_id(team)
+          # In ruby 1.8 doing a Integer(:symbol) returns an integer. Thus, test
+          # for symbol first.
+          if team.is_a? Symbol
+            teams.fetch(team)
+          else
+            Integer(team)  rescue teams.fetch(team.to_sym)
+          end
+        rescue IndexError
+          fail BadConfig, "No team id defined for team #{team}."
+        end
+      end
+    end
+  end
+end

data/lib/warden/github/rails/controller_helpers.rb

@@ -0,0 +1,35 @@
+module Warden
+  module GitHub
+    module Rails
+      module ControllerHelpers
+        # Initiates the OAuth flow if not already authenticated for the
+        # specified scope.
+        def github_authenticate!(scope=Rails.default_scope)
+          request.env['warden'].authenticate!(:scope => scope)
+        end
+
+        # Logs out a user if currently logged in for the specified scope.
+        def github_logout(scope=Rails.default_scope)
+          request.env['warden'].logout(scope)
+        end
+
+        # Checks whether a user is logged in for the specified scope.
+        def github_authenticated?(scope=Rails.default_scope)
+          request.env['warden'].authenticated?(scope)
+        end
+
+        # Returns the currently signed in user for the specified scope. See the
+        # documentation for Warden::GitHub::User for available methods.
+        def github_user(scope=Rails.default_scope)
+          request.env['warden'].user(scope)
+        end
+
+        # Accessor for the currently signed in user's session. This will be
+        # cleared once logged out.
+        def github_session(scope=Rails.default_scope)
+          request.env['warden'].session(scope)  if github_authenticated?(scope)
+        end
+      end
+    end
+  end
+end

data/lib/warden/github/rails/railtie.rb

@@ -0,0 +1,27 @@
+module Warden
+  module GitHub
+    module Rails
+      class Railtie < ::Rails::Railtie
+        config.app_middleware.use Warden::Manager do |config|
+          config.failure_app = lambda { |env| [403, {}, [env['warden'].message]] }
+          Rails.warden_config = config
+          Rails.scopes.each do |scope, scope_config|
+            config.scope_defaults scope, :strategies => [:github],
+                                         :config => scope_config
+          end
+        end
+
+        initializer 'warden-github-rails.controller_helpers' do
+          ActiveSupport.on_load(:action_controller) do
+            include ControllerHelpers
+          end
+
+          ActiveSupport.on_load(:action_view) do
+            include ViewHelpers
+          end
+        end
+      end
+    end
+  end
+end
+

data/lib/warden/github/rails/routes.rb

@@ -0,0 +1,83 @@
+module Warden
+  module GitHub
+    module Rails
+      module Routes
+        # Enforces an authenticated GitHub user for the routes. If not
+        # authenticated, it initiates the OAuth flow.
+        #
+        # Team and organization memberships can be checked by specifying a hash
+        # such as `:team => 'foobar'` or `:org => 'my_company'`.
+        def github_authenticate(scope=nil, options={}, &routes_block)
+          github_constraint(scope, options, routes_block) do |warden, scope|
+            warden.authenticate!(:scope => scope)
+          end
+        end
+
+        # The routes will only be visible to authenticated GitHub users. When
+        # not authenticated, it does not initiate the OAuth flow.
+        #
+        # Team and organization memberships can be checked by specifying a hash
+        # such as `:team => 'foobar'` or `:org => 'my_company'`.
+        def github_authenticated(scope=nil, options={}, &routes_block)
+          github_constraint(scope, options, routes_block) do |warden, scope|
+            warden.authenticated?(:scope => scope)
+          end
+        end
+
+        # The routes will only be visible to all but authenticated GitHub users.
+        #
+        # This constraint currently does not check for memberships since of its
+        # limited usage.
+        def github_unauthenticated(scope=nil, options={}, &routes_block)
+          github_constraint(scope, options, routes_block) do |warden, scope|
+            not warden.authenticated?(:scope => scope)
+          end
+        end
+
+        private
+
+        def github_constraint(scope, options, routes_block, &block)
+          options, scope = scope, nil  if scope.is_a? Hash
+          scope ||= Rails.default_scope
+
+          constraint = lambda do |request|
+            warden = request.env['warden']
+
+            if block.call(warden, scope)
+              if (user = warden.user(scope))
+                evaled_options = github_eval_options(options, request)
+                github_enforce_options(user, evaled_options)
+              else
+                true
+              end
+            end
+          end
+
+          constraints(constraint, &routes_block)
+        end
+
+        def github_enforce_options(user, options)
+          if (team = options[:team])
+            user.team_member?(Rails.team_id(team))
+          elsif (org = options[:org] || options[:organization])
+            user.organization_member?(org)
+          else
+            true
+          end
+        end
+
+        def github_eval_options(options, request)
+          Hash[options.map { |k,v|
+            if v.is_a?(Proc)
+              [k, v.call(request)]
+            else
+              [k, v]
+            end
+          }]
+        end
+      end
+    end
+  end
+end
+
+ActionDispatch::Routing::Mapper.send(:include, Warden::GitHub::Rails::Routes)