kdonovan-trufina 0.1.0

data/.gitignore

@@ -0,0 +1 @@
+rdoc/

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 [name of plugin creator]
+
+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.rdoc

@@ -0,0 +1,116 @@
+= Trufina
+
+The Trufina gem provides a DSL allowing you to easily interface with {Trufina.com}[http://www.trufina.com]'s identity verification API.  
+Trufina[http://www.trufina.com] provides an identity verification service, and this DSL basically lets you request verified information
+from the user (who provides that information directly to Trufina[http://www.trufina.com], and then uses their website to control
+permissions of who can access what parts of their personal data).
+
+== Requirements
+
+Before you begin you'll need to fill out some paperwork with Trufina[http://www.trufina.com] and, after a bit of administrative mucking around, 
+you'll be given two important identifiers: a PID (Partner ID) and a PAK (Partner Authentication Key).  Place these in
+your +config/trufina.yml+ file, replace the other defaults, and you'll be good to go.
+
+== Installation
+
+Getting the code on your system is as simple as
+
+  script/plugin install git://github.com/kdonovan/trufina.git
+  
+or
+
+  gem sources -a http://gems.github.com
+  sudo gem install kdonovan-trufina
+  
+
+Once you have the code, you'll need to create a +trufina.yml+ file in your project's config directory.  If you don't
+do this by hand, a template file will be created automatically the first time you load your application after installation.
+Trufina will raise a ConfigFileError until you fill out the config file with meaningful data.
+
+
+== Example
+
+Once installation has been completed, using the code itself is really easy -- the most complicated step is understanding
+Trufina[http://www.trufina.com]'s various flows.  We'll walk through an example:
+
+  # We'll skip it here for verbosity, but note that you can turn on debugging
+  # to print out pretty versions of any XML sent or received.
+  # Trufina::Config.debug = true
+
+Say we have a user in our database for whom we want verified information.  The first step is to
+establish a session key with Trufina[http://www.trufina.com] so we can associate later responses with this request.  This
+is done by sending them a PRT (Partner Request Token), which can be any arbitrary value. In a real app
+I'd probably use a user-id + timestamp combination, but for this demo we'll use the {random number}[http://xkcd.com/221/] 4.
+
+Note that you can also specify what data you want access to (name, address, country of birth, etcetera),
+as well as any default values you may already know to prefill the form on the Trufina[http://www.trufina.com] website.  See
+Trufina.login_url or Trufina.login_request for more details, but the default is to request the user's first and last name.
+
+  Trufina.login_url(4, :demo => true) # => http://staging.trufina.com/DemoPartnerLogin/DemoLogin/6ZEeENWWD8@K
+  
+
+You can now visit this URL to create an account for a fake user on Trufina[http://www.trufina.com]'s demo server. When you're done,
+you'll be redirected to whatever you put as your success endpoint in +trufina.yml+, and there will be a TLID
+(Temporary Login ID) appended.  In my case it was 870.  You have 15 minutes to use this TLID to access the 
+information about the user Trufina[http://www.trufina.com] has verified.
+
+  info = Trufina.login_info_request(870)
+  info.data.present_and_verified # => [{:name=>[{:first=>"TEST_FIRNAME"}, {:surname=>"TEST_SURNAME"}]}] (or whatever names you entered on the staging server)
+
+
+That completes the simplest use-case.  Say we decide we want more information about the user, like their middle 
+name.  We send Trufina[http://www.trufina.com] an access request, and if the user has already provided the information and given us 
+permission we'll get the info back immediately.
+
+  new_info = Trufina.access_request(info, {:name => [:middle]})
+  new_info.data.present_and_verified # => [{:name=>[{:middle=>"SomeMiddleName"}]}]
+
+
+Note that here our demo user has already given Trufina[http://www.trufina.com] permission to see all the name components, so we get 
+the middle name back immediately.  For a different component where Trufina[http://www.trufina.com] needs to ask the user there's no 
+useful data in the response (the XML contains a "pending" node, but the gem doesn't bother parsing it out).
+
+  Trufina.access_request(info, [:phone]).data.present_and_verified # => []
+
+
+In this case we would receive an AccessNotification to our servers once the user gave us permission to access
+the requested data, and at that point we'd be able to re-request the data with another Trufina.access_request 
+call, for which the newly requested data would show up like the middle name did above.
+
+
+== Advanced Topics
+
+=== Seed Info
+
+Trufina.login_request (and therefore Trufina.login_url, which is just a wrapper) allows you to pass along seed 
+data used to prepopulate the fields the user will encounter on Trufina.com (see Trufina::Elements::SeedInfoGroup 
+for all options).  Prepopulated data will be specified as the value of a :seed key in the options hash of either
+method. Example:
+
+  Trufina.login_request(4, :seed => {:name => {:first => 'Foo', :surname => 'Bar'}})
+
+=== Request Data
+
+A number of the API calls allow you to supply a list of the data you'd like returned about the user in question.
+You may do this as follows:
+
+  Trufina.login_request(4, :requested => [:age, {:name => [:first, :middle, :surname]}])
+
+or
+
+  Trufina.access_request({:pur => 4, :prt => 4}, [:age, {:name => [:first, :middle, :surname]}])
+
+
+== Unsupported functionality
+
+* Does not handle requesting comparisons or other request attributes
+  * (Note that Trufina[http://www.trufina.com] itself doesn't support maxAge or timeframe yet)
+* Setting ResidenceAddress seed data isn't yet supported
+
+== Compatibility
+
+The goal of this module is to be relatively framework agnostic.  That being said, I've personally only tried to use it
+in conjunction with a Rails application.  If you run into problems trying to use it elsewhere, well... patches happily
+accepted. :)
+
+Copyright (c) 2009 Kali Donovan, released under the MIT license

data/Rakefile

@@ -0,0 +1,53 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "trufina"
+    gem.summary = %Q{DSL to easily interact with Trufina's verification API}
+    gem.description = %Q{Provides a DSL to easily interact with the XML API offered by Trufina.com, an identity verification company.}
+    gem.email = "kali.donovan@gmail.com"
+    gem.homepage = "http://github.com/kdonovan/trufina"
+    gem.authors = ["Kali Donovan"]
+    gem.add_dependency "jimmyz-happymapper"
+  end
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the trufina plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the trufina plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Trufina API'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.rdoc_files.exclude('init.rb')
+  rdoc.rdoc_files.exclude('rails/init.rb')
+end
+
+# gem 'darkfish-rdoc'
+# require 'darkfish-rdoc'
+# 
+# Rake::RDocTask.new(:darkfish) do |rdoc|
+#   rdoc.title    = "Trufina API"
+#   rdoc.rdoc_files.include 'README.rdoc'
+# 
+#   rdoc.options += [
+#     '-SHN',
+#     '-f', 'darkfish',  # This is the important bit
+#   ]
+# end

data/TODO

@@ -0,0 +1,8 @@
+PENDING:
+  * Schema validation against the provided .xsd fails
+  * Unable to set ResidenceAddress in seed data (e.g. Trufina.login_request(4, :seed => {:residence_address => {:state => 'CA'}}))
+    Yields error: Attribute 'timeframe' must appear on element 'ResidenceAddress' (noted in README)
+
+UNSUPPORTED:
+  * Setting StreetAddress seed data is unsupported (will generate extra <.> tags, and it is unclear how to set multiple lines)
+  * Comparison or other request attributes (note that maxAge and timeframe are not even supported by Trufina yet)

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/init.rb

@@ -0,0 +1 @@
+require File.join(File.dirname(__FILE__), 'rails', 'init')

data/lib/config.rb

@@ -0,0 +1,62 @@
+class Trufina
+  # Reads in configuration data from config/trufina.yml (and handles creating it if missing / complaining if it looks unfilled).
+  class Config
+    cattr_accessor  :credentials, :staging_access, :endpoints,
+                    :app_root, :config_file, :mode, :debug
+    
+    # Allow range of config locations
+    self.app_root          = RAILS_ROOT if defined?(RAILS_ROOT)
+    self.app_root          = Merb.root  if defined?(Merb)
+    self.app_root        ||= app_root
+    self.app_root        ||= Dir.pwd
+    self.config_file       = File.join(self.app_root, 'config', 'trufina.yml')
+
+    # Symbolize hash keys - defined here so we don't rely on Rails
+    def self.symbolize_keys!(hash) # :nodoc:
+      return hash unless hash.is_a?(Hash)
+      
+      hash.keys.each do |key|
+        unless key.is_a?(Symbol)
+          hash[key.to_sym] = hash[key]
+          hash.delete(key)
+        end
+      end
+      hash
+    end
+
+    # Ensure config exists
+    unless File.exists?(self.config_file)
+      config_template = File.join(File.dirname(__FILE__), '..', 'trufina.yml.template')
+      File.copy(config_template, self.config_file)
+      raise Exceptions::ConfigFileError.new("Unable to create configuration template at #{self.config_file}") unless File.exists?(self.config_file)
+    end
+    
+    # Load keys from config file into the class
+    YAML.load(ERB.new(File.read(self.config_file)).result).each do |key, value|
+      self.send("#{key}=", symbolize_keys!(value)) if self.methods.include?("#{key}=")
+    end
+    
+    # Set default mode unless already set in the config file
+    unless %w(production staging).include?(self.mode)
+      env = defined?(Merb) ? ENV['MERB_ENV'] : ENV['RAILS_ENV']
+      @@mode = env && env == 'production' ? 'production' : 'staging'
+    end
+    
+    # Ensure template file has been modified with (hopefully) real data
+    if self.credentials.any?{|k,v| v == 'YOUR_DATA_HERE'}
+      raise Exceptions::ConfigFileError.new("Don't forget to update the Trufina config file with your own data! File is located at #{self.config_file}")
+    end
+    
+    # Syntactic sugar for setting and checking the current operating mode
+    class << self
+      %w(staging production).each do |mode|
+        define_method("#{mode}!"){ @@mode = mode }
+        define_method("#{mode}?"){ @@mode == mode }
+      end
+      def debug?
+        !!@@debug
+      end
+    end
+    
+  end
+end

data/lib/elements.rb

@@ -0,0 +1,170 @@
+# Contains smaller classes (essentially HappyMapper element classes) used to create and
+# parse API calls and responses.
+
+class Trufina
+  
+  # Handle creating a HappyMapper object from array or hash (creating empty nodes as required).
+  module AllowCreationFromHash
+    
+    def initialize(seed_data = {})
+      seed_data.is_a?(Array) ? create_empty_nodes(seed_data) : create_nodes(seed_data)
+    end
+
+    protected
+    
+    # e.g. Trufina::Name.new([:first, :suffix]) - no values provided, print empty nodes
+    #
+    #     <Name>
+    #       <First/>
+    #       <Suffix/>
+    #     </Name>
+    def create_empty_nodes(nodes)
+      nodes.each do |node|
+        create_node(node)
+      end
+    end
+
+    # e.g. Trufina::Name.new({:first => 'Bob', :suffix => 'III'}) - print nodes with values
+    # 
+    #     <Name>
+    #       <First>Bob</First>
+    #       <Suffix>III</Suffix>
+    #     </Name>
+    def create_nodes(nodes)
+      nodes.each do |node, content|
+        create_node(node, content)
+      end
+    end
+    
+    # Handle the actual node creation
+    def create_node(name, content = nil)
+      case name
+      when Array then create_empty_nodes(name)
+      when Hash then create_nodes(name)
+      else
+        element   = self.class.elements.detect{|e| e.method_name.to_sym == name}
+        raise Exceptions::InvalidElement.new("No known element named '#{name}'") unless element
+
+        value = if HappyMapper::Item::Types.include?(element.type)
+          content ? content : ''
+        else 
+          content ? element.type.new(content) : element.type.new
+        end
+        self.send("#{name}=", value)
+      end
+    end
+    
+  end
+
+  module Elements
+    RESPONSE_XML_ATTRIBUTES = {:state => String, :age => String, :charged => String, :status => String, :errors => String }
+
+    module EasyElementAccess
+      
+      # Shortcut to collecting any information that's present and available
+      def present_and_verified
+        yes = []
+        self.class.elements.map(&:method_name).each  do |p|
+          next unless val = self.send(p)
+          
+          if val.respond_to?(:present_and_verified)
+            yes << {p.to_sym => val.present_and_verified}
+          else
+            yes << {p.to_sym => val} if val.state == 'verified' && val.status == 'present'
+          end
+        end
+        yes
+      end
+      
+    end
+    
+    # Encapsulates the various name components Trufina accepts
+    class Name
+      include AllowCreationFromHash
+      include HappyMapper
+      include EasyElementAccess
+      tag 'Name'
+  
+      element :prefix,  String, :tag => 'Prefix',               :attributes => RESPONSE_XML_ATTRIBUTES
+      element :first,   String, :tag => 'First',                :attributes => RESPONSE_XML_ATTRIBUTES
+      element :middle,  String, :tag => 'MiddleName',           :attributes => RESPONSE_XML_ATTRIBUTES
+      element :middle_initial, String, :tag => 'MiddleInitial', :attributes => RESPONSE_XML_ATTRIBUTES
+      element :surname, String, :tag => 'Surname',              :attributes => RESPONSE_XML_ATTRIBUTES
+      element :suffix,  String, :tag => 'Suffix',               :attributes => RESPONSE_XML_ATTRIBUTES
+    end
+    
+    # Wrapper attempting to allow access to multiple StreetAddress tags per single ResidenceAddress
+    class StreetAddress
+      include AllowCreationFromHash
+      include HappyMapper
+      include EasyElementAccess
+      tag 'StreetAddress'
+      
+      element :name, String, :tag => '.', :attributes => RESPONSE_XML_ATTRIBUTES
+    end
+
+    # Encapsulates Trufina's address fields
+    class ResidenceAddress
+      include AllowCreationFromHash
+      include HappyMapper
+      include EasyElementAccess
+      tag 'ResidenceAddress'
+
+      has_many :street_addresses, StreetAddress,  :tag => 'StreetAddress',  :attributes => RESPONSE_XML_ATTRIBUTES
+      element :city,              String,         :tag => 'City',           :attributes => RESPONSE_XML_ATTRIBUTES
+      element :state,             String,         :tag => 'State',          :attributes => RESPONSE_XML_ATTRIBUTES
+      element :postal_code,       String,         :tag => 'PostalCode',     :attributes => RESPONSE_XML_ATTRIBUTES
+    end
+
+    # Encapsulates all response data Trufina may send back
+    class AccessResponseGroup
+      include AllowCreationFromHash
+      include HappyMapper
+      include EasyElementAccess
+      tag 'AccessResponse'
+  
+      element :name,              Name,     :single => true,          :attributes => RESPONSE_XML_ATTRIBUTES
+      # element :birth_date,        Date,     :tag => 'DateOfBirth',    :attributes => RESPONSE_XML_ATTRIBUTES
+      # element :birth_country,     String,   :tag => 'CountryOfBirth', :attributes => RESPONSE_XML_ATTRIBUTES
+      element :phone,             String,   :tag => 'Phone',          :attributes => RESPONSE_XML_ATTRIBUTES
+      element :residence_address, ResidenceAddress, :single => true,  :attributes => RESPONSE_XML_ATTRIBUTES
+      element :ssn,               String,   :tag => 'fullSSN',        :attributes => RESPONSE_XML_ATTRIBUTES
+      element :last_4_ssn,        String,   :tag => 'Last4SSN',       :attributes => RESPONSE_XML_ATTRIBUTES
+      element :age,               String,   :tag => 'Age',            :attributes => RESPONSE_XML_ATTRIBUTES
+    end
+
+    # Encapsulates all data we can request from Trufina
+    class AccessRequest
+      include AllowCreationFromHash
+      include HappyMapper
+      tag 'AccessRequest'
+  
+      element :name,              Name,     :single => true
+      element :birth_date,        Date,     :tag => 'DateOfBirth'
+      element :birth_country,     String,   :tag => 'CountryOfBirth'
+      element :phone,             String,   :tag => 'Phone'           # If Trufina implemented it, could have timeframe and maxAge attributes
+      element :residence_address, ResidenceAddress, :single => true   # If Trufina implemented it, could have timeframe and maxAge attributes
+      element :ssn,               String,   :tag => 'fullSSN'
+      element :last_4_ssn,        String,   :tag => 'Last4SSN'
+      element :age,               String,   :tag => 'Age',            :attributes => {:comparison => String}
+    end
+    
+    # Encapsulates all seed data Trufina accepts
+    class SeedInfoGroup
+      include AllowCreationFromHash
+      include HappyMapper
+      tag 'SeedInfo'
+      
+      element :name,              Name,     :single => true
+      element :email,             String,   :single => true
+      element :birth_date,        Date,     :tag => 'DateOfBirth'
+      element :birth_country,     String,   :tag => 'CountryOfBirth'
+      element :phone,             String,   :tag => 'Phone'
+      element :residence_address, ResidenceAddress, :single => true
+      element :ssn,               String,   :tag => 'fullSSN'
+      element :last_4_ssn,        String,   :tag => 'Last4SSN'
+      element :age,               String,   :tag => 'Age'
+    end
+    
+  end
+end

data/lib/exceptions.rb

@@ -0,0 +1,15 @@
+# This file defines all Trufina Exceptions
+
+class Trufina
+  module Exceptions
+    class TrufinaException < StandardError; end
+    class ConfigFileError < TrufinaException; end
+    class MissingToken < TrufinaException; end
+    class MissingRequiredElements < TrufinaException; end
+    class MissingRequiredAttributes < TrufinaException; end
+    class InvalidElement < TrufinaException; end
+    class NetworkError < TrufinaException; end
+    class UnknownResponseType < TrufinaException; end
+    class TrufinaResponseException < TrufinaException; end
+  end
+end