trufina 0.2.5

data/.gitignore

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

data/CHANGELOG

@@ -0,0 +1,16 @@
+0.2.4 [September 07, 2009]
+  * Switching from jimmyz-happymapper to kdonovan-happymapper, which includes ability to Marshal happymapped objects
+
+0.2.3 [September 07, 2009]
+  * Added a to_s method for Trufina::Elements::Name and Trufina::Elements::ResidenceAddressResponse
+
+0.2.2 [September 04, 2009]
+  * Fixed bug in present_and_verified where it choked handling arrays
+  * API Change: modified present_and_verified return value to be more direct (nested hashes rather than alternating hashes and arrays of hashes)
+
+0.2.1 [September 04, 2009]
+  * Embedded basic auth information directly in redirect URL when in staging mode
+
+0.2.0 [September 04, 2009]
+  * Finally supporting ResidenceAddress seed and request data
+  * API Change: using zip rather than postal_code

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,179 @@
+= 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
+  
+  # Add this to environment.rb
+  config.gem 'kdonovan-trufina', :lib => 'trufina', :source => "http://gems.github.com"
+  
+
+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.
+
+
+== Examples
+
+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=>"FIRSTNAME"}, {:last=>"LASTNAME"}} (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', :last => '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, :last]}])
+
+or
+
+  Trufina.access_request({:pur => 4, :prt => 4}, [:age, {:name => [:first, :middle, :last]}])
+
+Note that an array item creates an empty node (e.g. <age/>) unless it's a hash, in which case it creates a node named from the hash key containing and recurses into the hash value inside the node.  That is to say,
+
+  :name => [:first, :middle, :last]
+  
+will generate something like:
+
+  <name>
+    <first/>
+    <middle/>
+    <last/>
+  </name>
+  
+which is exactly the format Trufina requires to indicate we want to receive the first and middle names of the specified user.  Note that the gem does some additional work to hide irregularities of the Trufina API from the user (i.e. you), so the above code really renders:
+
+  <Name>
+    <First/>
+    <MiddleName/>
+    <Surname/>
+  </Name>
+
+(meaning you don't have to remember that Trufina randomly uses Surname, and breaks their convention by using MiddleName rather than simply Middle).
+
+== Rails Integration
+
+Personally, I set up a controller dedicated to handling Trufina's postbacks (Success, Failure, and Cancel) as well as their AccessNotification.  If (as I'd suggest) you use the +current_user+'s ID as your PRT, then when a user wants to sign up with Trufina:
+
+  redirect_url = Trufina.login_url(current_user.id, :requested => REQUESTED_DATA, :seed => SEED_DATA)
+
+
+
+The biggest gotcha is that Trufina only uses the PRT for the login_info_request / login_info_response messages -- after that they use their own identifier (the PUR) to indicate which user a given response refers to, so you'll need to store the PUR provided in the login_info_request somewhere and use that going forward. Your success action will end up looking something like this:
+
+  def success
+    info = Trufina.login_info_request( params[:tlid )
+    user = User.find(info.prt)
+    user.pur = info.pur
+    ...
+  end
+
+
+Also, note that an AccessNotification will be sent immediately upon a new user's registration with Trufina.  You can just ignore any AccessNotification with an unknown PUR value, or it's also possible to use the Trufina.info_request in response to this first AccessNotification and avoid using the login_info_response altogether.
+
+Once you've verified the user, you just need to handle any AccessNotifications you may receive:
+
+  def handle_access_notification
+    tnid = params[:trufina_access_notification][:tnid]
+    info = Trufina.info_request( tnid )
+    user = User.find_by_pur( info.pur )
+
+    # Now take appropriate actions to handle user either revoking or adding 
+    # permissions for you to access certain subsets of their verified data.
+    ...
+  end
+
+
+
+
+== 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)
+
+== API Version
+
+This is compatible with the latest Trufina API version as of the creation date: Trufina API 1.0.4
+
+
+== 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,54 @@
+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 "kdonovan-happymapper"
+  end
+  Jeweler::GemcutterTasks.new
+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,5 @@
+PENDING:
+  * Schema validation against the provided .xsd fails
+
+UNSUPPORTED:
+  * Comparison or other request attributes (note that maxAge and timeframe are not even supported by Trufina yet)

data/VERSION

@@ -0,0 +1 @@
+0.2.5

data/init.rb

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

data/lib/config.rb

@@ -0,0 +1,64 @@
+require 'fileutils'
+
+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')
+      FileUtils.cp(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,203 @@
+# 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 = {})
+      create_nodes(seed_data)
+
+      # Define attributes
+      self.class.attributes.each do |attr|
+        self.send("#{attr.method_name}=", nil) unless self.send(attr.method_name)
+      end
+      
+      # Define elements
+      self.class.attributes.each do |elem|
+        self.send("#{elem.method_name}=", nil) unless self.send(elem.method_name)
+      end
+    end
+
+    protected
+    
+    def create_nodes(data)
+      data.each do |key, value|
+        create_node(key, value)
+      end
+    end
+    
+    # Handle the actual node creation
+    def create_node(name, content = nil)
+      return create_nodes(name) if content.nil? && name.is_a?(Hash) # Handle accidentally passing in a full hash
+      
+      element   = self.class.elements.detect{|e| e.method_name.to_sym == name}
+      raise Exceptions::InvalidElement.new("No known element named '#{name}'") unless element || self.respond_to?("#{name}=")
+      
+      case name
+      when Hash then create_nodes(name)
+      when Array  then create_empty_nodes(name)
+      else
+        value = if content.nil?
+          make_object?(element) ? element.type.new : ''
+        elsif content.is_a?(Array) && (element && !element.options[:single])
+          # If elements expects multiple instances, instantiate them all (e.g. StreetAddresses)
+          # Note that this assumes the object (only known case is Trufina::Elements::StreetAddress) has a :name element
+          out = content.collect do |local_content|
+            make_object?(element) ? element.type.new(:name => local_content) : local_content
+          end
+        else
+          make_object?(element) ? element.type.new(content) : content
+        end
+        
+        self.send("#{name}=", value)
+      end
+    end
+    
+    # Returns false if the given content is a simple type like a string, and we should just assign it.
+    # Returns true if the given content is another HappyMapper class, and we should instantiate the class 
+    # rather than merely assigning the value.
+    def make_object?(element)
+      element && !HappyMapper::Item::Types.include?(element.type)
+    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)
+          element = self.class.elements.detect{|e| e.method_name == p}
+          
+          if val.respond_to?(:present_and_verified)
+            yes[p.to_sym] = val.present_and_verified
+          elsif element.options[:single]
+            yes[p.to_sym] = val if val.state == 'verified' && val.status == 'present'
+          else # street_addresses is an array...
+            values = []
+            val.each do |array_item|
+              values << array_item if array_item.state == 'verified' && array_item.status == 'present'
+            end
+            yes[p.to_sym] = values
+          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 :last,    String, :tag => 'Surname',              :attributes => RESPONSE_XML_ATTRIBUTES
+      element :suffix,  String, :tag => 'Suffix',               :attributes => RESPONSE_XML_ATTRIBUTES
+      
+      def to_s
+        name_parts = self.class.elements.map(&:method_name)
+        name_parts.collect {|name_part| self.send(name_part) }.compact.join(' ')
+      end
+    end
+    
+    # Encapsulates Trufina's address fields - has multiple street address fields
+    class ResidenceAddressResponse
+      include AllowCreationFromHash
+      include HappyMapper
+      include EasyElementAccess
+      tag 'ResidenceAddress'
+
+      has_many :street_addresses, String,         :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 :zip,               String,         :tag => 'PostalCode',     :attributes => RESPONSE_XML_ATTRIBUTES
+      attribute :timeframe,       String
+
+      def street_address=(adr)
+        self.street_addresses ||= []
+        self.street_addresses << adr
+      end
+      
+      def to_s
+        [street_addresses[0], street_addresses[1], city, state, zip].compact.join(', ')
+      end
+    end
+    
+    # Encapsulates Trufina's address fields - only one street address field
+    class ResidenceAddressRequest
+      include AllowCreationFromHash
+      include HappyMapper
+      include EasyElementAccess
+      tag 'ResidenceAddress'
+
+      element :street_address,    String,         :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 :zip,               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
+      # 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 :age,               String,   :tag => 'Age',            :attributes => RESPONSE_XML_ATTRIBUTES
+      element :residence_address, ResidenceAddressResponse,           :single => true
+      element :ssn,               String,   :tag => 'fullSSN',        :attributes => RESPONSE_XML_ATTRIBUTES
+      element :last_4_ssn,        String,   :tag => 'Last4SSN',       :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 :age,               String,   :tag => 'Age',            :attributes => {:comparison => String}
+      element :residence_address, ResidenceAddressRequest,            :single => true   # If Trufina implemented it, could have timeframe and maxAge attributes
+      element :ssn,               String,   :tag => 'fullSSN'
+      element :last_4_ssn,        String,   :tag => 'Last4SSN'
+    end
+    
+    # Encapsulates all seed data Trufina accepts
+    class SeedInfoGroup
+      include AllowCreationFromHash
+      include HappyMapper
+      tag 'SeedInfo'
+      
+      element :name,              Name,     :single => true
+      element :birth_date,        Date,     :tag => 'DateOfBirth'
+      element :birth_country,     String,   :tag => 'CountryOfBirth'
+      element :phone,             String,   :tag => 'Phone'
+      element :age,               String,   :tag => 'Age'
+      element :residence_address, ResidenceAddressResponse,           :single => true
+      element :ssn,               String,   :tag => 'fullSSN'
+      element :last_4_ssn,        String,   :tag => 'Last4SSN'
+    end
+    
+  end
+end