passport 0.0.1 → 0.1.1

data/README.markdown

@@ -1 +1,183 @@
-# Passport
+# [Passport](http://authlogic-connect.heroku.com)
+
+> Oauth and OpenId made Dead Simple.
+
+Note: This is a refactoring and abstraction of [AuthlogicConnect](http://github.com/viatropos/authlogic-connect) and it is not yet complete.  The goal is to make it as low level as possible while still making it extremely simple to setup.  It will abstract away all Oauth/OpenID complexities and be pluggable into any existing authentication framework.
+
+Passport is your single interface to Oauth 1.0, Oauth 2.0, and OpenID.
+
+Allow your users to login with Github, Facebook, Twitter, Google, LinkedIn, MySpace, Vimeo, and Yahoo Oauth providers ([complete list](https://github.com/viatropos/passport/tree/master/lib/passport/oauth/tokens)), and all the OpenID providers.  Simple, Clean, Fast.
+
+## Usage
+
+### 1. Install
+
+    sudo gem install passport
+    
+### 2. Configure
+
+#### Add the gem dependencies in your config
+
+Rails 2.3.x: `config/environment.rb`
+
+    config.gem "passport"
+
+Rails 3: `Gemfile`
+
+    gem "passport"
+
+Ruby:
+
+    require "passport"
+    
+#### Specify your keys and secrets
+
+In a yaml file, say `config/passport.yml`, write your keys and secrets for each service you would like to support.  You have to manually go to the websites and register with the service provider.
+
+    adapter: active_record
+    services:
+      twitter:
+        key: "my_key"
+        secret: "my_secret"
+        label: "Twitter"
+      facebook:
+        key: "my_key"
+        secret: "my_secret"
+        label: "Facebook"
+      google:
+        key: "my_key"
+        secret: "my_secret"
+        label: "Google"
+      yahoo:
+        key: "my_key"
+        secret: "my_secret"
+        label: "Yahoo"
+      myspace:
+        key: "my_key"
+        secret: "my_secret"
+      vimeo:
+        key: "my_key"
+        secret: "my_secret"
+      linked_in:
+        key: "my_key"
+        secret: "my_secret"
+      
+Then in your application's initialization process:
+    
+    Passport.configure("config/passport.yml")
+
+## Adapters
+
+In the `config/passport.yml`, you can specify an `adapter`.  The adapter tells Passport what kind of class we want the `AccessToken` to be.  The choices are:
+
+- `object`
+- `active_record`
+- `mongo`
+
+### Plain Ruby Objects
+
+By default, if an `adapter` is not specified, `AccessToken` will be a plain-old Ruby [`Object`](http://ruby-doc.org/core/classes/Object.html).  This means the framework does not have any large dependencies by default, which is useful if you're making a quick and dirty Sinatra app for example, and just want super-simple Oauth support without a database.
+
+### ActiveRecord
+
+If you want to use this with ActiveRecord, setting up migrations is easy.  Check out the [Rails 3 AuthlogicConnect example](http://github.com/viatropos/authlogic-connect-example) for an authlogic example with user/session/access_token migrations.  The migrations table we have been using so far look like this:
+
+    class CreateAccessTokens < ActiveRecord::Migration
+      def self.up
+        create_table :access_tokens do |t|
+          t.integer :user_id
+          t.string :type, :limit => 30 #=> service as a class name
+          t.string :key # how we identify the user, in case they logout and log back in (e.g. email)
+          t.string :token, :limit => 1024
+          t.string :secret
+          t.boolean :active # whether or not it's associated with the account
+          t.timestamps
+        end
+        
+        add_index :access_tokens, :key, :unique
+      end
+      
+      def self.down
+        drop_table :access_tokens
+      end
+    end
+
+### MongoDB
+
+MongoDB doesn't require any migrations so it's a simple setup.  Just specify the mongo adapter in `config/passport.yml`:
+
+    adapter: mongo
+
+## API
+
+There's a lot of functionality packed into Passport.  All you need to know is that every service out there (Facebook, Twitter, Github, Foursquare, etc.) is treated as a `Token`.  The `OauthToken` (most of this is Oauth right now) has these key methods and attributes:
+
+- `Token.authorize(callback_url, headers)`: get the authorize url from the oauth provider
+- `Token.access(hash)`: get the access token from the oauth provider
+- `key`: the unique identifier for this user (optional, but definitely recommended)
+- `token`: oauth token from service
+- `secret`: oauth secret from service
+- `get(url, options)`: authenticated api GET to the service; pass in headers, params, etc.
+- `post(url, body, options)`: authenticated api POST to the service
+
+This means that instead of having to [write lots of code](http://github.com/intridea/oauth2) to setup even a simple oauth handler in your app, you can do this (sinatra example):
+
+    require 'rubygems'
+    require 'passport'
+    
+    Passport.configure("tokens.yml")
+    
+    get "/" do
+      "<a href='/authenticate?oauth_provider=facebook'>Login with Facebook</a>"
+    end
+    
+    get "/authenticate" do
+      Passport.authenticate
+    end
+    
+This also means that if you wanted to do your own oauth setup, with or without any framework, you can easily do that.  Say you want to programmatically setup Facebook Oauth with Mechanize (!):
+
+    def facebook_oauth
+      authorize_hash = FacebookToken.authorize("http://some-real-or-fake-callback-url/")
+      # mechanically submit forms
+      access_hash    = FacebookToken.access(authorize_hash)
+      # boom, you have the access token (token, key, and secret), now go exploring
+    end
+
+### Architecture
+
+You can accomplish everything oauth in Passport without using a server.  All you need to do is call these two methods: `Token.authorize` and `Token.access`.
+
+If you want to use a server (Sinatra, Rails, etc.), then Passport uses [Rack](http://github.com/chneukirchen/rack).  It keeps track of the state of the handshake using the `Rack::Session`.
+
+### Extending
+
+You can easily add your own services to Passport by creating an `OauthToken` subclass.  This is the `FacebookToken` example:
+
+    class FacebookToken < OauthToken
+  
+      version 2.0
+  
+      key do |access_token|
+        user = JSON.parse(access_token.get("/me"))
+        user["id"]
+      end
+  
+      settings "https://graph.facebook.com",
+        :authorize_url => "https://graph.facebook.com/oauth/authorize",
+        :scope         => "email, offline_access"
+  
+    end
+  
+There are 3 executable class methods that define the API to the Oauth provider:
+
+1. `version`: defaults to `1.0`, can also be `2.0`
+2. `key`: a `block` or symbol that results in something that uniquely identifies the user (e.g `email`, or a service-specific `id`)
+3. `settings`: the service domain, and a hash of the oauth urls and scopes
+
+## Lists of known providers
+
+- [Oauth Providers](http://wiki.oauth.net/ServiceProviders)
+- [More Oauth Providers](http://www.programmableweb.com/apis/directory/1?auth=OAuth)
+- [OpenID Providers](http://en.wikipedia.org/wiki/List_of_OpenID_providers)
+- [More OpenID Providers](http://openid.net/get-an-openid/)

data/Rakefile

@@ -2,21 +2,21 @@ require 'rake'
 require "rake/rdoctask"
 require 'rake/gempackagetask'
 
+# http://docs.rubygems.org/read/chapter/20
 spec = Gem::Specification.new do |s|
   s.name              = "passport"
-  s.author            = "Lance Pollard"
-  s.version           = "0.0.1"
-  s.summary           = "Passport: Oauth and OpenID made dead simple"
+  s.version           = IO.read("VERSION")
+  s.platform          = Gem::Platform::RUBY
+  s.authors           = ["Lance Pollard"]
+  s.email             = ["lancejpollard@gmail.com"]
+  s.summary           = "Oauth and OpenID made dead simple"
+  s.description       = "Ruby Oauth and OpenID library that abstracts away all the complexities of connecting to multiple accounts."
   s.homepage          = "http://github.com/viatropos/passport"
-  s.email             = "lancejpollard@gmail.com"
-  s.description       = "Oauth and OpenID made dead simple"
   s.has_rdoc          = true
   s.rubyforge_project = "passport"
-  s.platform          = Gem::Platform::RUBY
-  s.files             = %w(README.markdown Rakefile init.rb MIT-LICENSE) + Dir["{lib,rails,test}/**/*"] - Dir["test/tmp"]
+  s.files             = %w(README.markdown Rakefile init.rb MIT-LICENSE VERSION) + Dir["{lib,rails,test}/**/*"] - Dir["test/tmp"]
   s.require_path      = "lib"
   s.add_dependency("activesupport", ">= 2.1.2")
-  s.add_dependency("activerecord", ">= 2.1.2")
   s.add_dependency("json")
   s.add_dependency("ruby-openid")
   s.add_dependency("rack-openid", ">=0.2.1")
@@ -24,21 +24,16 @@ spec = Gem::Specification.new do |s|
   s.add_dependency("oauth2")
 end
 
-Rake::GemPackageTask.new(spec) do |pkg|
-  pkg.gem_spec    = spec
-  pkg.package_dir = "pkg"
-end
-
 desc "Create .gemspec file (useful for github)"
 task :gemspec do
-  File.open("pkg/#{spec.name}.gemspec", "w") do |f|
+  File.open("#{spec.name}.gemspec", "w") do |f|
     f.puts spec.to_ruby
   end
 end
 
 desc "Build the gem into the current directory"
 task :gem => :gemspec do
-  `gem build pkg/#{spec.name}.gemspec`
+  `gem build #{spec.name}.gemspec`
 end
 
 desc "Publish gem to rubygems"
@@ -55,8 +50,13 @@ task :manifest do
   end
 end
 
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec    = spec
+  pkg.package_dir = "pkg"
+end
+
 desc "Install the gem locally"
-task :install => [:package] do
+task :install => [:manifest, :package] do
   sh %{gem install pkg/#{spec.name}-#{spec.version} --no-ri --no-rdoc}
 end
 
@@ -78,6 +78,6 @@ task :test do
     next unless File.extname(file) == ".rb"
     next unless File.basename(file) =~ /test_/
     next if File.basename(file) =~ /test_helper/
-    system "ruby #{file}"
+    require file
   end
 end

data/VERSION

@@ -0,0 +1 @@
+0.1.1

data/lib/passport.rb

@@ -1,38 +1,22 @@
-require 'active_record'
-require "rubygems"
+require 'rubygems'
+require 'active_support'
+require 'active_support/core_ext'
+require 'rack'
+require 'json'
+require 'yaml'
 require 'oauth'
 require 'oauth2'
 
-this = File.dirname(__FILE__)
+this = File.expand_path(File.dirname(__FILE__))
 library = "#{this}/passport"
 
-require "#{this}/open_id_authentication"
-require "#{library}/ext"
-require "#{library}/passport"
-require "#{library}/callback_filter"
-require "#{library}/access_token"
-require "#{library}/openid"
-require "#{library}/oauth"
-require "#{library}/common"
-require "#{library}/engine" if defined?(Rails) && Rails::VERSION::MAJOR == 3
-
-custom_models =   ["#{library}/access_token"]
-custom_models +=  Dir["#{library}/oauth/tokens"]
-custom_models +=  Dir["#{library}/openid/tokens"]
+Dir["#{library}/helpers/*"].each { |file| require file }
+Dir["#{library}/core/*"].each { |file| require file }
 
-# Rails 3/2 config
-load_path_method = ActiveSupport::Dependencies.respond_to?(:autoload_paths) ? :autoload_paths : :load_paths
+require "#{library}/openid/protocol"
+require "#{library}/engine" if defined?(Rails) && Rails::VERSION::MAJOR == 3
 
-custom_models.each do |path|
-  $LOAD_PATH << path
-  ActiveSupport::Dependencies.send(load_path_method) << path
-end
+# require "#{library}/openid"
+require "#{library}/passport"
 
-# Rails 3beta4 backport
-if defined?(ActiveSupport::HashWithIndifferentAccess)
-  ActiveSupport::HashWithIndifferentAccess.class_eval do
-    def symbolize_keys!
-      symbolize_keys
-    end
-  end
-end
+Passport.root = "#{this}/.."

data/lib/passport/core/certification.rb

@@ -0,0 +1,47 @@
+module Passport
+  module Certification
+    def self.included(base)
+      base.extend ClassMethods
+    end
+    
+    module ClassMethods
+      def process?
+        Passport::Oauth::Protocol.request?# || Passport::OpenId::Protocol.start?
+      end
+      alias start? process?
+    
+      def process(user = nil)
+        protocol.process(user) if protocol
+      end
+      alias start process
+      
+      def approve?
+        Passport::Oauth::Protocol.response? # || Passport::OpenId::Protocol.complete?
+      end
+      alias complete? approve?
+      
+      def approve(user = nil)
+        protocol.approve(user) if protocol
+      end
+      alias complete approve
+      
+      def authenticate(user = nil, &block)
+        if process?
+          process(user) # redirect to service
+        elsif approve?
+          token = approve(user)
+          yield(token) if block_given?
+          token
+        end
+      end
+      
+      def protocol
+        if Passport::Oauth::Protocol.active?
+          Passport::Oauth::Protocol
+        # elsif Passport::OpenId::Protocol.using?
+          #Passport::OpenId::Protocol
+        end
+      end
+    end
+  end
+end

data/lib/passport/core/context.rb

@@ -0,0 +1,74 @@
+module Passport
+  module Context
+    def self.included(base)
+      base.extend ClassMethods
+    end
+    
+    module ClassMethods
+      def find(key)
+        Rack::Context.find(key)
+      end
+      
+      def session
+        Rack::Context.session
+      end
+      
+      def session_key(key)
+        Rack::Context.session_key(key)
+      end
+      
+      def params
+        Rack::Context.params
+      end
+      
+      def params_key(key)
+        Rack::Context.params_key(key)
+      end
+      
+      def redirect(url)
+        if controller = Thread.current[:rails_context]
+          controller.redirect_to(url)
+        else
+          puts "REDIRECT #{url}"
+          response = Rack::Response.new
+          response.redirect(url)
+          response.finish
+        end
+      end
+      
+      # if we've said it's a "user" (registration), or a "session" (login)
+      def authentication_type
+        find(:authentication_type)
+      end
+      
+      def authentication_method
+        find(:authentication_method)
+      end
+      
+      def clear
+        [:auth_request_class,
+          :authentication_type,
+          :auth_method,
+          :auth_attributes,
+          :oauth_provider,
+          :auth_callback_method
+        ].each { |key| Rack::Context.delete_session_key(key) }
+      end
+      
+      def debug
+        puts "=== BEGIN DEBUG ==="
+        puts "Passport.process? #{Passport.process?}"
+        puts "Passport.approve? #{Passport.approve?}"
+        puts "Passport::Oauth::Protocol.request? #{Passport::Oauth::Protocol.request?.inspect}"
+        puts "Passport::Oauth::Protocol.params? #{Passport::Oauth::Protocol.params?.inspect}"
+        puts "Passport::Oauth::Protocol.provider? #{Passport::Oauth::Protocol.provider?.inspect}"
+        puts "Passport::Oauth::Protocol.response? #{Passport::Oauth::Protocol.response?.inspect}"
+        puts "Passport::Oauth::Protocol.session? #{Passport::Oauth::Protocol.session?.inspect}"
+        puts "Passport::Oauth::Protocol.token? #{Passport::Oauth::Protocol.token?.inspect}"
+        puts "Session #{session.inspect}"
+        puts "Params #{params.inspect}"
+        puts "=== END DEBUG ==="
+      end
+    end
+  end
+end

data/lib/passport/core/installation.rb

@@ -0,0 +1,40 @@
+module Passport
+  module Installation
+    def self.included(base)
+      base.extend ClassMethods
+    end
+    
+    module ClassMethods
+      attr_accessor :installed
+      
+      def install
+        return if installed
+        
+        require "#{root}/lib/passport/support/#{adapter}"
+        require "#{root}/lib/passport/oauth"
+        
+        if defined?(Rails)          
+          custom_models = ["#{root}/lib/passport/support/#{adapter}"] + Dir["#{root}/lib/passport/oauth/tokens"]
+          #custom_models +=  Dir["#{library}/openid/tokens"]
+          
+          # Rails 3/2 config
+          load_path_method = ActiveSupport::Dependencies.respond_to?(:autoload_paths) ? :autoload_paths : :load_paths
+          
+          custom_models.each do |path|
+            $LOAD_PATH << path
+            ActiveSupport::Dependencies.send(load_path_method) << path
+          end
+        end
+        
+        if defined?(ActionController::Base)
+          ActionController::Base.helper(Passport::Oauth::ViewHelper)
+        end
+        if defined?(ActionView::Helpers::FormBuilder)
+          ActionView::Helpers::FormBuilder.send(:include, Passport::Oauth::ViewHelper)
+        end
+        
+        installed = true
+      end
+    end
+  end
+end