alterego 0.0.2 → 0.0.3

data/Guardfile

@@ -0,0 +1,21 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard 'rspec', :version => 2 do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+
+  # Rails example
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^app/(.+)\.rb$})                           { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{^lib/(.+)\.rb$})                           { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch(%r{^app/controllers/(.+)_(controller)\.rb$})  { |m| ["spec/routing/#{m[1]}_routing_spec.rb", "spec/#{m[2]}s/#{m[1]}_#{m[2]}_spec.rb", "spec/acceptance/#{m[1]}_spec.rb"] }
+  watch(%r{^spec/support/(.+)\.rb$})                  { "spec" }
+  watch('spec/spec_helper.rb')                        { "spec" }
+  watch('config/routes.rb')                           { "spec/routing" }
+  watch('app/controllers/application_controller.rb')  { "spec/controllers" }
+  # Capybara request specs
+  watch(%r{^app/views/(.+)/.*\.(erb|haml)$})          { |m| "spec/requests/#{m[1]}_spec.rb" }
+end
+

data/README.rdoc

@@ -1,22 +1,50 @@
 = AlterEgo
 
-AlterEgo is a Ruby gem for interacting with the {AlterEgo}[https://alteregoapp.com] API. AlterEgo adds an extra layer of security to your web app to thwart phishing attacks and breaches caused by insecure passwords. It generates temporary auth codes only accessible on users' mobile devices and makes them required for entry.
-
-== Requirements
-
-You will need an {AlterEgo}[https://alteregoapp.com] account. More detailed instructions about generating API keys and granting access here...
+AlterEgo is a Ruby gem for integrating {AlterEgo}[https://alteregoapp.com] two-factor authentication into your web application. You'll need an {AlterEgo account}[https://alteregoapp.com/#signupfree] in order to register your {register your app}[https://alteregoapp.com/app/register] and get your "App Authentication ID".
 
 == Installation
 
   (sudo) gem install alterego
 
-== Usage
+== Authorizing Your Application
+
+In order to use AlterEgo, users of your application will need to sign up for their own {AlterEgo account}[https://alteregoapp.com/#signupfree]. You will need your users to authorize the connection between your application and {AlterEgo}[https://alteregoapp.com] by simply redirecting them:
+
+  redirect_to AlterEgo.authorization_url("your_app_id", "https://yourapp.com/alterego/callback")
+
+{AlterEgo}[https://alteregoapp.com] imposes the following requirements on the +redirect_url+ value to ensure security. Be sure that your +redirect_url+ meets the following requirements:
+
+- Must be served via HTTPS.
+- Must be under the same domain (or a subdomain of) the website entered when registering your application with {AlterEgo}[https://alteregoapp.com].
+
+Once authorized successfully, a POST request will be sent to the +redirect_url+ with a "key" parameter containing the API key for that user's {AlterEgo}[https://alteregoapp.com] account. Be sure to store this key somewhere, as you will need it to run API requests later. If authorization fails for some reason, an "error" parameter will be present in the POST request, containing an error message.
+
+  if params[:key]
+    current_user.alter_ego_key = params[:key]
+  elsif params[:error]
+    flash[:alert] = params[:error]
+  end
+
+== Authenticating With AlterEgo
+
+Once your users have authorized your application and you have retrieved an API key for their account, you can easily integrate two-factor authentication. To authenticate using {AlterEgo}[https://alteregoapp.com] (either as part of an existing login process, or as a stand-alone authentication system) simply prompt the user to input a valid {AlterEgo}[https://alteregoapp.com] passcode and verify it:
+
+  passcode = params[:alter_ego_passcode]
+  if AlterEgo.password(current_user.alter_ego_key, passcode)
+    # Passcode is valid.
+    ...
+  else
+    # Passcode is not valid.
+    ...
+  end
 
-Please refer to the {AlterEgo API Documentation}[https://alteregoapp.com/apidocs/v1.0/] for information.
+{AlterEgo}[https://alteregoapp.com] does not provide any kind of error message or explanation as to why a passcode is not valid, so you will want to be sure and keep your error messages appropriately generic.
 
-...
+== Pinging The API
 
+The {AlterEgo}[https://alteregoapp.com] API also has a method for pinging the API, in case you want to periodically check to ensure that your user's API keys are still valid. A successful ping to the API will always return "PONG!" as a response.
 
+  AlterEgo.ping(current_user.alter_ego_api_key)
 
 == Contributing to AlterEgo
  

data/Rakefile

@@ -18,7 +18,7 @@ Jeweler::Tasks.new do |gem|
   gem.homepage = "http://github.com/terra-firma/alterego"
   gem.license = "MIT"
   gem.summary = %Q{Ruby gem for interacting with the AlterEgo API.}
-  gem.description = %Q{AlterEgo is a Ruby gem that provides a wrapper for interacting with the AlterEgo web app authentication service API.}
+  gem.description = %Q{AlterEgo is a Ruby gem for integrating two-factor authentication into your web application.}
   gem.email = "brian@terra-firma-design.com"
   gem.authors = ["Brian Getting"]
   # dependencies defined in Gemfile

data/VERSION

@@ -1 +1 @@
-0.0.2
+0.0.3

data/alterego.gemspec

@@ -0,0 +1,69 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{alterego}
+  s.version = "0.0.3"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = [%q{Brian Getting}]
+  s.date = %q{2011-10-17}
+  s.description = %q{AlterEgo is a Ruby gem for integrating two-factor authentication into your web application.}
+  s.email = %q{brian@terra-firma-design.com}
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+    "Gemfile",
+    "Guardfile",
+    "LICENSE.txt",
+    "README.rdoc",
+    "Rakefile",
+    "VERSION",
+    "alterego.gemspec",
+    "lib/alterego.rb",
+    "spec/alterego/alterego_spec.rb",
+    "spec/alterego/fixtures/error.json",
+    "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/terra-firma/alterego}
+  s.licenses = [%q{MIT}]
+  s.require_paths = [%q{lib}]
+  s.rubygems_version = %q{1.8.8}
+  s.summary = %q{Ruby gem for interacting with the AlterEgo API.}
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<json>, [">= 0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<fakeweb>, [">= 0"])
+      s.add_development_dependency(%q<guard-rspec>, [">= 0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.6.4"])
+      s.add_development_dependency(%q<rcov>, [">= 0"])
+      s.add_development_dependency(%q<rspec>, [">= 0"])
+    else
+      s.add_dependency(%q<json>, [">= 0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<fakeweb>, [">= 0"])
+      s.add_dependency(%q<guard-rspec>, [">= 0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.6.4"])
+      s.add_dependency(%q<rcov>, [">= 0"])
+      s.add_dependency(%q<rspec>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<json>, [">= 0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<fakeweb>, [">= 0"])
+    s.add_dependency(%q<guard-rspec>, [">= 0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.6.4"])
+    s.add_dependency(%q<rcov>, [">= 0"])
+    s.add_dependency(%q<rspec>, [">= 0"])
+  end
+end
+

data/lib/alterego.rb

@@ -3,4 +3,81 @@ require 'uri'
 require 'rubygems'
 require 'json'
 
-require 'alterego/api'
+class AlterEgo
+  
+  API_URL = "https://alteregoapp.com/api"
+  AUTH_URL = "http://alteregoapp.com/account/authorize-app"
+  
+  # Generate an AlterEgo +authorization_url+.
+  # Returns a URL to redirect users to so that they will be prompted
+  # to enter their AlterEgo username and password to authorize a
+  # connection between your application and their AlterEgo account.
+  #
+  # If authorized successfully, a POST request will be sent to the
+  # +redirect_url+ with a "key" parameter containing the API key for
+  # that user's AlterEgo account. Be sure to store this key somewhere,
+  # as you will need it to run API requests later.
+  #
+  # If authorization fails for some reason, an "error" parameter will
+  # be present in the POST request, containing an error message.
+  #
+  # == A note about callback URL's:
+  #
+  # AlterEgo imposes the following requirements on the +redirect_url+ value
+  # to ensure security. Be sure that your +redirect_url+ meets the following
+  # requirements:
+  #
+  # - Must be served via HTTPS.
+  # - Must be under the same domain (or a subdomain of) the website entered
+  #   when registering your application with AlterEgo.
+  #
+  # == Example
+  #
+  # redirect_to AlterEgo.authorization_url("12345","https://example.com/callback")
+  #
+  def self.authorization_url(app_id, redirect_url)
+    # TODO: Encode the redirect_url.
+    "#{AUTH_URL}?id=#{app_id}&redirect_url=#{URI.escape(redirect_url, Regexp.new("[^#{URI::PATTERN::UNRESERVED}]"))}"
+  end
+  
+  # Ping the AlterEgo API.
+  # Returns either "PONG!" (indicating a successful connection to the API) or
+  # an error.
+  #
+  # == Example
+  #
+  # AlterEgo.ping("valid_api_key")
+  #
+  def self.ping(key)
+    call("#{API_URL}/check/ping.json?key=#{key}")
+  end
+  
+  # Check an AlterEgo passcode.
+  # Returns +true+ if the passcode if valid, and +false+ if the passcode is not
+  # valid.
+  #
+  # == Example
+  #
+  # AlterEgo.password("valid_api_key", "passcode")
+  #
+  def self.password(key, passcode)
+    call("#{API_URL}/check/password.json?key=#{key}&pass=#{passcode}")
+  end
+  
+  private
+  
+  def self.call(url) # :nodoc:
+    response = Net::HTTP.get_response(URI.parse(url))
+    raise AlterEgo::APIError.new(response.body) if response.code.to_i == 500
+    return nil if response.body == ''
+    response.body
+  end
+  
+  class APIError < StandardError
+    def initialize(response) # :nodoc:
+      error = JSON.parse(response)
+      super "<#{error['code']}> #{error['name']}: #{error['message']}"
+    end
+  end
+  
+end

data/spec/alterego/alterego_spec.rb

@@ -1,7 +1,52 @@
 require 'spec_helper'
 
-module AlterEgo
-  describe API do
+describe AlterEgo do
 
+  describe "authorization_url" do
+    it "should require an app_id and redirect_url" do
+      expect {AlterEgo.authorization_url}.should raise_error(ArgumentError)
+      expect {AlterEgo.authorization_url(@app_id)}.should raise_error(ArgumentError)
+      expect {AlterEgo.authorization_url(@app_id, @callback_url)}.should_not raise_error(ArgumentError)
+    end
+
+    it "should generate an authorization URL" do
+      @callback_url = 'https://test.com/callback'
+      url = AlterEgo.authorization_url(@app_id, @callback_url)
+      url.should eq("#{AlterEgo::AUTH_URL}?id=#{@app_id}&redirect_url=#{URI.escape(@callback_url, Regexp.new("[^#{URI::PATTERN::UNRESERVED}]"))}")
+    end
+  end
+
+  describe "API" do
+    API_URL = "http://alteregoapp.com:443/api/check"
+    
+    it "should require a key when pinging" do
+      expect {AlterEgo.ping}.should raise_error(ArgumentError)
+    end
+    
+    it "should return 'PONG!' when pinging successfully" do
+      FakeWeb.register_uri(:get, "#{API_URL}/ping.json?key=#{@api_key}", :body => "PONG!")
+      AlterEgo.ping(@api_key).should eq("PONG!")
+    end
+    
+    it "should require a key and passcode when checking password" do
+      expect {AlterEgo.password}.should raise_error(ArgumentError)
+      expect {AlterEgo.password(@api_key)}.should raise_error(ArgumentError)
+    end
+    
+    it "should return true when the passcode matches" do
+      FakeWeb.register_uri(:get, "#{API_URL}/password.json?key=#{@api_key}&pass=#{@passcode}", :body => "true")
+      AlterEgo.password(@api_key, @passcode).should eq("true")
+    end
+    
+    it "should return false when the passcode doesn't match" do
+      FakeWeb.register_uri(:get, "#{API_URL}/password.json?key=#{@api_key}&pass=#{@passcode}", :body => "false")
+      AlterEgo.password(@api_key, @passcode).should eq("false")
+    end
+    
+    it "should respond to 500 errors from the API" do
+      FakeWeb.register_uri(:get, "#{API_URL}/password.json?key=#{@api_key}&pass=#{@passcode}", :body => @error, :status => ["500", "Internal Server Error"])
+      expect {AlterEgo.password(@api_key, @passcode)}.should raise_error(AlterEgo::APIError)
+    end
   end
-end
+
+end

data/spec/alterego/fixtures/error.json

@@ -0,0 +1,6 @@
+{
+	"status": "error",
+	"code": 0,
+	"name": "Error",
+	"message": "A random error occurred"
+}

data/spec/spec_helper.rb

@@ -6,5 +6,10 @@ FakeWeb.allow_net_connect = false
 RSpec.configure do |config|
   config.before(:each) do
     FakeWeb.clean_registry
+    @app_id       = 'valid-app-id'
+    @api_key      = 'valid-api-key'
+    @callback_url = 'https://example.com/callback'
+    @passcode     = 'alter-ego-passcode'
+    @error        = File.read(File.expand_path('spec/alterego/fixtures/error.json'))
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: alterego
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-10-12 00:00:00.000000000Z
+date: 2011-10-17 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
-  requirement: &2153544280 !ruby/object:Gem::Requirement
+  requirement: &2153522520 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2153544280
+  version_requirements: *2153522520
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &2153540900 !ruby/object:Gem::Requirement
+  requirement: &2153520800 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: 1.0.0
   type: :development
   prerelease: false
-  version_requirements: *2153540900
+  version_requirements: *2153520800
 - !ruby/object:Gem::Dependency
   name: fakeweb
-  requirement: &2153538600 !ruby/object:Gem::Requirement
+  requirement: &2153518960 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2153538600
+  version_requirements: *2153518960
 - !ruby/object:Gem::Dependency
   name: guard-rspec
-  requirement: &2153536960 !ruby/object:Gem::Requirement
+  requirement: &2153517220 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2153536960
+  version_requirements: *2153517220
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &2153535960 !ruby/object:Gem::Requirement
+  requirement: &2153515440 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -65,10 +65,10 @@ dependencies:
         version: 1.6.4
   type: :development
   prerelease: false
-  version_requirements: *2153535960
+  version_requirements: *2153515440
 - !ruby/object:Gem::Dependency
   name: rcov
-  requirement: &2153534680 !ruby/object:Gem::Requirement
+  requirement: &2153512980 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,10 +76,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2153534680
+  version_requirements: *2153512980
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2153532960 !ruby/object:Gem::Requirement
+  requirement: &2153510180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,9 +87,9 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2153532960
-description: AlterEgo is a Ruby gem that provides a wrapper for interacting with the
-  AlterEgo web app authentication service API.
+  version_requirements: *2153510180
+description: AlterEgo is a Ruby gem for integrating two-factor authentication into
+  your web application.
 email: brian@terra-firma-design.com
 executables: []
 extensions: []
@@ -99,13 +99,15 @@ extra_rdoc_files:
 files:
 - .document
 - Gemfile
+- Guardfile
 - LICENSE.txt
 - README.rdoc
 - Rakefile
 - VERSION
+- alterego.gemspec
 - lib/alterego.rb
-- lib/alterego/api.rb
 - spec/alterego/alterego_spec.rb
+- spec/alterego/fixtures/error.json
 - spec/spec_helper.rb
 homepage: http://github.com/terra-firma/alterego
 licenses:
@@ -122,7 +124,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2984477021801594771
+      hash: -3242706057364793623
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:

data/lib/alterego/api.rb

@@ -1,12 +0,0 @@
-module AlterEgo
-  class API
-    # TODO: Put this together...
-  end
-  
-  class APIError < StandardError
-    def initialize(error)
-      super("<#{error.faultCode}> #{error.message}")
-    end
-  end
-
-end