TeleAuth 0.5

data/README

@@ -0,0 +1,106 @@
+== Synopsis
+
+Ruby TeleAuth Module.
+
+Allows for two-factor authentication within Ruby. Uses the
+TeleAuth[http://www.teleauth.com] service.
+
+== Author
+
+Mohit Muthanna Cheppudira <mohit AT muthanna DOTcom>
+
+== Copyright
+
+Copyright (c) 2005 Mohit Muthanna Cheppudira.
+Licensed under the GPL.
+
+== Prerequisites
+
+To use this module, you will need a TeleAuth API Key. Get yours
+at [http://www.teleauth.com].
+
+== Basic Usage
+
+The following example calls a user on a specific phone
+number and requests a PIN code.
+
+  require 'teleauth'
+
+  conn = TeleAuth::Client.new (
+    'urls' = ['http://teleauth.com/api/auth'],
+    'domain_id' = 'mydomain',
+    'login' = 'dialer',
+    'password' = 'bu4ger'
+    )
+
+Register a user's phone number.
+
+  conn.register_phone( 
+    'ext_uid' => 'foobar', 
+    'phone' => '12332445443'
+    )
+
+Call user and request PIN code.
+
+  conn.get_secret( 'ext_uid' => 'foobar' ) { |response|
+    puts "PIN code: #{ response['secret'] }"
+  }
+
+
+== TeleAuth API 
+
+In brief, you can use any API command as a TeleAuth::Client
+method. Arguments are provided as hash parameters. Responses
+are returned as Ruby hashes.
+
+Examples:
+
+  response = conn.validate_user
+
+  conn.validate_user { |response|
+    # do something
+  }
+
+Register a user's phone number and PIN code.
+
+  conn.register_phone( 
+    'ext_uid' => 'foobar', 
+    'phone' => '12332445443',
+    'pin' => '45334',
+    )
+
+Call the user and validate PIN
+
+  conn.validate_phone( 'ext_uid' => 'foobar' ) { |response|
+    if response['login'] == 'PASS'
+      puts "Valid PIN code."
+    else
+      puts "Authorization failed"
+    end
+  end
+
+
+For the TeleAuth API reference, visit http://teleauth.com
+
+== Logging, Exceptions and Errors
+
+The class raises the TeleAuth::APIError exception if the API command 
+failed.
+
+If you have multiple URLs, eg. for failover, the module can
+inform you if a failover took place.
+
+  conn.on_command_fail { |url|
+    puts "Failed to connect to #{ url }. Trying next one."
+  }
+
+
+If you need nice debug output, use on_log:
+
+  con.on_log { |msg|
+    $stderr.puts( "LOG: #{ msg }" )
+  end
+
+== Support
+
+Get on the {TeleAuth Mailing List}[http://lists.sourceforge.net/lists/listinfo/teleauth-users]

data/lib/teleauth.rb

@@ -0,0 +1,251 @@
+require 'uri'
+require 'yaml'
+require 'net/http'
+
+=begin rdoc
+
+== Synopsis
+
+Ruby TeleAuth Module.
+$Id$
+
+Allows for two-factor authentication within Ruby. Uses the
+TeleAuth[http://www.teleauth.com] service.
+
+== Author
+
+Mohit Muthanna Cheppudira mohit AT muthanna DOT com
+
+== Copyright
+
+Copyright (c) 2005 Mohit Muthanna Cheppudira.
+Licensed under the GPL.
+
+=end
+
+module TeleAuth
+
+=begin rdoc
+This exception is raised if an API command could 
+not be successfully sent to any of the TeleAuth
+URLs.
+=end
+
+class APIError < Exception; end
+
+=begin rdoc
+
+This is the TeleAuth Client Class. Basic usage:
+
+The following example calls a user on a specific phone
+number and requests a PIN code.
+
+  require 'teleauth'
+
+  conn = TeleAuth::Client.new (
+    'urls' = ['http://teleauth.com/api/auth'],
+    'domain_id' = 'mydomain',
+    'login' = 'dialer',
+    'password' = 'bu4ger'
+    )
+
+  # Register a user's phone number.
+  conn.register_phone(
+      'ext_uid' => 'foobar',
+      'phone' => '12332445443'
+      )
+
+  conn.get_secret( 'ext_uid' => 'foobar' ) { |response|
+    puts "PIN code: #{ response['secret'] }"
+  }
+
+=end
+
+class Client
+
+=begin rdoc
+  [auth] A hash that consists of API authentication parameters.
+  [urls] An array of API URLs.
+=end
+
+  attr_accessor :auth, :urls
+
+=begin rdoc
+At a minimum, this method requires a list of URLs, and 
+the API Key, like so:
+
+
+  conn = TeleAuth::Client.new( 
+    "urls" => ["http://teleauth.com/apu/auth", "http://backup.teleauth.com/api/auth"],
+    "domain_id" => "public.sample",
+    "login" => "admin",
+    "password" => "p4ss"
+  )
+
+The URLs are a list of primary and failover API servers. When
+an API command is sent, each of these servers are cycled through
+until one of them works.
+=end
+  
+  def initialize( params = {} )
+    if params.has_key?( 'urls' )
+      self.urls = params['urls']
+
+      # Delete this key, as it shouldn't be passed in
+      # the API request.
+      params.delete( 'urls' )
+    else
+      self.urls = []
+    end
+
+    @auth = params
+    @on_command_fail = proc {}
+    @on_log = proc {}
+  end
+
+=begin rdoc
+Setup a code-block to execute if one of the URLs fail. This could
+be useful for logging, for example. It passes the URL of the API
+server that failed.
+
+  conn.on_command_fail { |url|
+    $stderr.puts "Failed to send command to #{ url }"
+  }
+=end
+
+  def on_command_fail( &block )
+    @on_command_fail = block
+  end
+
+=begin rdoc
+Our logger. Call this and specify a logging routing to receive more
+debug information.
+
+  conn.on_log { |msg|
+    $stderr.puts "LOG: #{ msg }"
+  end
+=end
+
+  def on_log( &block )
+    @on_log = block
+  end
+
+  def log( *args )
+    @on_log.call( *args )
+  end
+
+=begin rdoc
+The main communications routine. Establish a connection to the API
+server, and send the command. Private.
+=end
+
+  def api_send( command_hash )
+
+    # For each URL...
+    @urls.each do |url|
+      log( "Trying #{ url }" )
+      uri = URI.parse( url )
+
+      # Make sure it's HTTP/(S) ...
+      if uri.scheme == "http"
+        response = ""
+
+        # Build the POST parameters..
+        post_params = command_hash.keys.collect { |key|
+          key + "=" + command_hash[key]
+        }.join( "&" )
+
+        log( "Sending: #{ post_params }" )
+
+        begin
+          Net::HTTP.start( uri.host ) do |query|
+            response = query.post( uri.path, post_params )
+          end
+
+          log( "Response: #{ response.message }" )
+
+          if response.message == "OK"
+            log( "Body: #{ response.body }" )
+            return response.body
+          else
+            # HTTP level failure...
+            @on_command_fail.call( url )
+            next
+          end 
+        rescue Exception => e
+          # Socket level failure...
+          @on_command_fail.call( url )
+          next
+        end
+      else
+        # Unsupported URI scheme...
+        @on_command_fail.call( url )
+      end
+    end
+  
+    # All failed. Return Nil.
+    return nil
+  end
+
+=begin rdoc
+This method creates a hash with parameters for api_send
+=end
+  def send_command( *args )
+    # Extract the instance method name
+    command = args.shift
+
+    # No Arguments?
+    if (params = args.shift).nil?
+      params = Hash.new
+    end
+
+    # Pass the extracted method name as the API command
+    command_hash = auth.merge( params ).merge( 'cmd' => command.to_s )
+    response = api_send( command_hash )
+
+    raise APIError if response.nil?
+    response
+  end
+
+=begin rdoc
+Check to see if we have connectivity by sending a "version" API command.
+=end
+
+  def ping?
+    begin
+      version
+    rescue Exception => e
+      return false
+    end
+
+    true
+  end 
+   
+=begin rdoc
+This is where the magic happens. Any instance method that is not defined
+reaches here. We just propogate the request to send_command, which 
+extracts the method name, and substitutes it for the API command. This
+get's fed to api_send.
+
+This function also yields to a code block, so commands can be sent in
+multiple forms:
+
+  conn.get_user_list { |user_list|
+    # ... do something with user_list
+  }
+
+or 
+
+  user_list = conn.get_user_list
+=end
+
+  def method_missing( *args )
+    response = YAML::load( send_command( *args ) )
+    yield response if block_given?
+    response
+  end
+
+  protected :api_send, :log
+end
+
+end

data/tests/ts_teleauth.rb

@@ -0,0 +1,54 @@
+#!/usr/bin/env ruby
+
+# PickAxe magic. Helps run tests from any directory.
+$:.unshift File.join( File.dirname( __FILE__ ), "..", "lib" )
+
+require 'teleauth'
+require 'test/unit'
+
+include TeleAuth
+
+=begin rdoc
+Test class for TeleAuth::Client.
+=end
+
+class TestClient < Test::Unit::TestCase
+  def setup
+
+    # Setup API Test parameters here. Make sure
+    # you use an invalid URL before a valid one
+    # to test failures.
+
+    @conn = Client.new( 
+      "urls" => ["http://abc.d/f", "http://teleauth.com/api/auth"],
+      "domain_id" => "public.test",
+      "login" => "reader",
+      "password" => "reader"
+    )
+  end
+
+  def teardown
+    # Nothing to do...
+  end
+ 
+  def test_ping
+    assert_equal( @conn.ping?, true )
+  end
+ 
+  def test_commands
+    failed = false
+    @conn.on_command_fail {
+      failed = true
+    }
+
+    # Test both formats of commands...
+    assert_equal( @conn.validate_user['result'], 'OK' )
+
+    @conn.validate_user { |response|
+      assert_equal response['result'], 'OK'
+    }
+
+    # The first URL should have failed.
+    assert_equal failed, true
+  end
+end

metadata

@@ -0,0 +1,41 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.10
+specification_version: 1
+name: TeleAuth
+version: !ruby/object:Gem::Version 
+  version: "0.5"
+date: 2005-08-26
+summary: Ruby library for the TeleAuth authentication system. Requires a TeleAuth API key.
+require_paths: 
+  - lib
+email: mohit@muthanna.com
+homepage: http://teleauth.com
+rubyforge_project: 
+description: 
+autorequire: teleauth
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+    - 
+      - ">"
+      - !ruby/object:Gem::Version 
+        version: 0.0.0
+  version: 
+platform: ruby
+authors: 
+  - Mohit Muthanna Cheppudira
+files: 
+  - lib/teleauth.rb
+  - tests/ts_teleauth.rb
+  - README
+test_files: 
+  - tests/ts_teleauth.rb
+rdoc_options: []
+extra_rdoc_files: 
+  - README
+executables: []
+extensions: []
+requirements: []
+dependencies: []