lperichon-contacts 1.0

data/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "vendor/fakeweb"]
+	path = vendor/fakeweb
+	url = git://github.com/mislav/fakeweb.git

data/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2009 Mislav Marohnić
+
+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.markdown

@@ -0,0 +1,111 @@
+## Contacts
+
+Fetch users' contact lists without asking them to provide their
+passwords, as painlessly as possible.
+
+Contacts provides adapters for:
+
+ * Google
+ * Yahoo!
+ * Windows Live
+
+## Basic usage instructions
+
+First, register your application with the service providers you
+require. Instructions below under "Setting up your accounts".
+
+Now, create a consumer:
+
+    consumer = Contacts::Google.new
+    consumer = Contacts::Yahoo.new
+    consumer = Contacts::WindowsLive.new
+    # OR by parameter:
+    # provider is one of :google, :yahoo, :windows_live
+    consumer = Contacts.new_consumer(provider)
+
+Now, direct your user to:
+
+    consumer.authentication_url(return_url)
+
+`return_url` is the page the user will be redirected to by the service
+once authorization has been granted. You should also persist the
+consumer object so you can grab the contacts once the user returns:
+
+    session[:consumer] = consumer.serialize
+
+Now in the request handler of the return_url above:
+
+    consumer = Contacts.deserialize(session[:consumer])
+    if consumer.authorize(params)
+      @contacts = consumer.contacts
+    else
+      # handle error
+    end
+
+Here, `params` is the hash of request parameters that the user returns
+with. `consumer.authorize` returns true if the authorization was
+successful, false otherwise.
+
+The list of `@contacts` are `Contacts::Contact` objects which have
+these attributes:
+
+ * name
+ * emails
+
+## Setting up your accounts
+
+### Google
+
+Set up your projects
+[here](http://code.google.com/apis/accounts/docs/RegistrationForWebAppsAuto.html).
+
+ * When redirecting to an unverified domain (e.g., localhost), the
+   user sees a warning when authorizing access.
+
+What this means:
+
+ * You can use the same consumer key for development as production.
+
+### Yahoo
+
+Set up your projects [here](https://developer.apps.yahoo.com/projects)
+
+ * When a project's domain is verified, you must redirect to it.
+ * When a project's domain is not verified, you can redirect anywhere, and the
+   user sees a warning when authorizing access.
+
+What this means:
+
+ * Set up separate production and development projects.
+ * Verify the domain of your production project. You will only be able to
+   redirect to your production domain when using this key.
+ * Don't verify the domain of your development project. You will be able to
+   redirect to any domain when using this key.
+
+## Windows Live
+
+Set up your projects [here](http://msdn.microsoft.com/en-us/library/cc287659.aspx).
+
+ * There is no domain verification step.
+ * The domain cannot be localhost, an IP address, or have a query string.
+ * You must redirect to the project's domain, on any port, and the URL may not
+   have a query string or fragment.
+ * You must specify a privacy policy URL.
+
+What this means:
+
+ * Set up separate production and development projects.
+ * For development, use a domain like myapp.local.
+ * Map this domain to 127.0.0.1 in /etc/hosts or a local DNS server.
+ * If you want to run your app on a different domain (e.g., localhost:3000),
+   redirect the POST from Windows Live to a GET on the original domain. This
+   ensures the popup window has the same origin as the opener page, in
+   accordance with browser same origin policies.
+
+## Copyright
+
+Copyright (c) 2010 [George Ogata](mailto:george.ogata@gmail.com) See
+LICENSE for details.
+
+Derived from [Mislav's Contacts](http://github.com/mislav/contacts),
+Copyright (c) 2009 [Mislav Marohnić](mailto:mislav.marohnic@gmail.com)

data/Rakefile

@@ -0,0 +1,55 @@
+require 'spec/rake/spectask'
+require 'rake/rdoctask'
+
+task :default => :spec
+
+spec_opts = 'spec/spec.opts'
+spec_glob = FileList['spec/**/*_spec.rb']
+libs = ['lib', 'spec', 'vendor/fakeweb/lib']
+
+desc 'Run all specs in spec directory'
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.libs = libs
+  t.spec_opts = ['--options', spec_opts]
+  t.spec_files = spec_glob
+  # t.warning = true
+end
+
+namespace :spec do
+  desc 'Analyze spec coverage with RCov'
+  Spec::Rake::SpecTask.new(:rcov) do |t|
+    t.libs = libs
+    t.spec_files = spec_glob
+    t.spec_opts = ['--options', spec_opts]
+    t.rcov = true
+    t.rcov_opts = lambda do
+      IO.readlines('spec/rcov.opts').map { |l| l.chomp.split(" ") }.flatten
+    end
+  end
+  
+  desc 'Print Specdoc for all specs'
+  Spec::Rake::SpecTask.new(:doc) do |t|
+    t.libs = libs
+    t.spec_opts = ['--format', 'specdoc', '--dry-run']
+    t.spec_files = spec_glob
+  end
+  
+  desc 'Generate HTML report'
+  Spec::Rake::SpecTask.new(:html) do |t|
+    t.libs = libs
+    t.spec_opts = ['--format', 'html:doc/spec.html', '--diff']
+    t.spec_files = spec_glob
+    t.fail_on_error = false
+  end
+end
+
+desc 'Generate RDoc documentation'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_files.add ['README.rdoc', 'MIT-LICENSE', 'lib/**/*.rb']
+  rdoc.main = 'README.rdoc'
+  rdoc.title = 'Ruby Contacts library'
+  
+  rdoc.rdoc_dir = 'doc'
+  rdoc.options << '--inline-source'
+  rdoc.options << '--charset=UTF-8'
+end

data/lib/contacts/consumer.rb

@@ -0,0 +1,123 @@
+module Contacts
+  class Consumer
+    #
+    # Configure this consumer from the given hash.
+    #
+    def self.configure(configuration)
+      @configuration = Util.symbolize_keys(configuration)
+    end
+
+    #
+    # The configuration for this consumer.
+    #
+    def self.configuration
+      @configuration
+    end
+
+    #
+    # Define an instance-level reader for the named configuration
+    # attribute.
+    #
+    # Example:
+    #
+    #     class MyConsumer < Consumer
+    #       configuration_attribute :app_id
+    #     end
+    #
+    #     MyConsumer.configure(:app_id => 'foo')
+    #     consumer = MyConsumer.new
+    #     consumer.app_id    # "foo"
+    #
+    def self.configuration_attribute(name)
+      class_eval <<-EOS
+        def #{name}
+          self.class.configuration[:#{name}]
+        end
+      EOS
+    end
+
+    def initialize(options={})
+    end
+
+    #
+    # Return a string of serialized data.
+    #
+    # You may reconstruct the consumer by passing this string to
+    # .deserialize.
+    #
+    def serialize
+      params_to_query(serializable_data)
+    end
+
+    #
+    # Create a consumer from the given +string+ of serialized data.
+    #
+    # The serialized data should have been returned by #serialize.
+    #
+    def self.deserialize(string)
+      data = string ? query_to_params(string) : {}
+      consumer = new
+      consumer.initialize_serialized(data) if data
+      consumer
+    end
+
+    #
+    # Authorize the consumer's token from the given
+    # parameters. +params+ is the request parameters the user is
+    # redirected to your site with.
+    #
+    # Return true if authorization is successful, false otherwise. If
+    # unsuccessful, an error message is set in #error. Authorization
+    # may fail, for example, if the user denied access, or the
+    # authorization is forged.
+    #
+    def authorize(params)
+      raise NotImplementedError, 'abstract'
+    end
+
+    #
+    # An error message for the last call to #authorize.
+    #
+    attr_accessor :error
+
+    #
+    # Return the list of contacts, or nil if none could be retrieved.
+    #
+    def contacts
+      raise NotImplementedError, 'abstract'
+    end
+
+    protected
+
+    def initialize_serialized(data)
+      raise NotImplementedError, 'abstract'
+    end
+
+    def serialized_data
+      raise NotImplementedError, 'abstract'
+    end
+
+    def self.params_to_query(params)
+      params.map do |key, value|
+        "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"
+      end.join('&')
+    end
+
+    def self.query_to_params(data)
+      params={}
+      data.split(/&/).each do |pair|
+        key, value = *pair.split(/=/)
+        params[CGI.unescape(key)] = value ? CGI.unescape(value) : ''
+      end
+      params
+    end
+
+    def params_to_query(params)
+      self.class.params_to_query(params)
+    end
+
+    def query_to_params(data)
+      self.class.query_to_params(data)
+    end
+  end
+end

data/lib/contacts/google.rb

@@ -0,0 +1,70 @@
+require 'nokogiri'
+
+module Contacts
+  class Google < OAuthConsumer
+    CONSUMER_OPTIONS = Util.frozen_hash(
+      :site => "https://www.google.com",
+      :request_token_path => "/accounts/OAuthGetRequestToken",
+      :access_token_path => "/accounts/OAuthGetAccessToken",
+      :authorize_path => "/accounts/OAuthAuthorizeToken"
+    )
+
+    REQUEST_TOKEN_PARAMS = Util.frozen_hash(
+      'scope' => "https://www.google.com/m8/feeds/"
+    )
+
+    def initialize(options={})
+      super(CONSUMER_OPTIONS, REQUEST_TOKEN_PARAMS)
+    end
+
+    def contacts(options={})
+      return nil if @access_token.nil?
+      params = {:limit => 200}.update(options)
+      google_params = translate_parameters(params)
+      query = params_to_query(google_params)
+      response = @access_token.get("/m8/feeds/contacts/default/thin?#{query}")
+      parse_contacts(response.body)
+    end
+
+    private
+
+    def translate_parameters(params)
+      params.inject({}) do |all, pair|
+        key, value = pair
+        unless value.nil?
+          key = case key
+                when :limit
+                  'max-results'
+                when :offset
+                  value = value.to_i + 1
+                  'start-index'
+                when :order
+                  all['sortorder'] = 'descending' if params[:descending].nil?
+                  'orderby'
+                when :descending
+                  value = value ? 'descending' : 'ascending'
+                  'sortorder'
+                when :updated_after
+                  value = value.strftime("%Y-%m-%dT%H:%M:%S%Z") if value.respond_to? :strftime
+                  'updated-min'
+                else key
+                end
+
+          all[key] = value
+        end
+        all
+      end
+    end
+
+    def parse_contacts(body)
+      document = Nokogiri::XML(body)
+      document.search('/xmlns:feed/xmlns:entry').map do |entry|
+        emails = entry.search('./gd:email[@address]').map{|e| e['address'].to_s}
+        next if emails.empty?
+        title = entry.at('title') and
+          name = title.inner_text
+        Contact.new(name, emails)
+      end.compact
+    end
+  end
+end

data/lib/contacts/oauth_consumer.rb

@@ -0,0 +1,70 @@
+require 'oauth'
+
+module Contacts
+  class OAuthConsumer < Consumer
+    configuration_attribute :consumer_key
+    configuration_attribute :consumer_secret
+
+    def initialize(consumer_options, request_token_params)
+      @consumer_options = consumer_options
+      @request_token_params = request_token_params
+    end
+
+    def initialize_serialized(data)
+      value = data['request_token'] and
+        @request_token = deserialize_oauth_token(consumer, value)
+      value = data['access_token'] and
+        @access_token = deserialize_oauth_token(consumer, value)
+    end
+
+    def serializable_data
+      data = {}
+      data['access_token'] = serialize_oauth_token(@access_token) if @access_token
+      data['request_token'] = serialize_oauth_token(@request_token) if @request_token
+      data
+    end
+
+    attr_accessor :request_token
+    attr_accessor :access_token
+
+    def authentication_url(target, options={})
+      @request_token = consumer.get_request_token({:oauth_callback => target}, @request_token_params)
+      @request_token.authorize_url
+    end
+
+    def authorize(params)
+      begin
+        @access_token = @request_token.get_access_token(:oauth_verifier => params['oauth_verifier'])
+      rescue OAuth::Unauthorized => error
+        @error = error.message
+      end
+    end
+
+    private
+
+    def consumer
+      @consumer ||= OAuth::Consumer.new(consumer_key, consumer_secret, @consumer_options)
+    end
+
+    #
+    # Marshal sucks for persistence. This provides a prettier, more
+    # future-proof persistable representation of a token.
+    #
+    def serialize_oauth_token(token)
+      params = {
+        'version' => '1',  # serialization format
+        'type' => token.is_a?(OAuth::AccessToken) ? 'access' : 'request',
+        'oauth_token' => token.token,
+        'oauth_token_secret' => token.secret,
+      }
+      params_to_query(params)
+    end
+
+    def deserialize_oauth_token(consumer, data)
+      params = query_to_params(data)
+      klass = params['type'] == 'access' ? OAuth::AccessToken : OAuth::RequestToken
+      token = klass.new(consumer, params.delete('oauth_token'), params.delete('oauth_token_secret'))
+      token
+    end
+  end
+end

data/lib/contacts/util.rb

@@ -0,0 +1,24 @@
+module Contacts
+  module Util
+    #
+    # Freeze the given hash, and any hash values recursively.
+    #
+    def self.frozen_hash(hash={})
+      hash.freeze
+      hash.keys.each{|k| k.freeze}
+      hash.values.each{|v| v.freeze}
+      hash
+    end
+
+    #
+    # Return a copy of +hash+ with the keys turned into Symbols.
+    #
+    def self.symbolize_keys(hash)
+      result = {}
+      hash.each do |key, value|
+        result[key.to_sym] = value
+      end
+      result
+    end
+  end
+end

data/lib/contacts/version.rb

@@ -0,0 +1,9 @@
+module Contacts
+  module VERSION #:nodoc:
+    MAJOR = 0
+    MINOR = 2
+    TINY  = 5
+
+    STRING = [MAJOR, MINOR, TINY].join('.')
+  end
+end

data/lib/contacts/windows_live.rb

@@ -0,0 +1,188 @@
+require 'nokogiri'
+
+module Contacts
+  class WindowsLive < Consumer
+    configuration_attribute :application_id
+    configuration_attribute :secret_key
+    configuration_attribute :privacy_policy_url
+
+    #
+    # If this is set, then #authentication_url will force the given
+    # +target+ URL to have this origin (= scheme + host + port). This
+    # should match the domain that your Windows Live project is
+    # configured to live on.
+    #
+    # Instead of calling #authorize(params) when the user returns, you
+    # will need to call #forced_redirect_url(params) to redirect the
+    # user to the true contacts handler. #forced_redirect_url will
+    # handle construction of the query string based on the incoming
+    # parameters.
+    #
+    # The intended use is for development mode on localhost, which
+    # Windows Live forbids redirection to. Instead, you may register
+    # your app to live on "http://myapp.local", set :force_origin =>
+    # 'http://myapp.local:3000', and map the domain to 127.0.0.1 via
+    # your local hosts file. Your handlers will then look something
+    # like:
+    #
+    #     def handler
+    #       if ENV['HTTP_METHOD'] == 'POST'
+    #         consumer = Contacts::WindowsLive.new
+    #         redirect_to consumer.authentication_url(session)
+    #       else
+    #         consumer = Contacts::WindowsLive.deserialize(session[:consumer])
+    #         consumer.authorize(params)
+    #         contacts = consumer.contacts
+    #       end
+    #     end
+    #
+    # Since only the origin is forced -- not the path part of the URL
+    # -- the handler typically redirects to itself. The second time
+    # through it is a GET request.
+    #
+    # Default: nil
+    #
+    # Example: http://myapp.local
+    #
+    configuration_attribute :force_origin
+
+    def initialize(options={})
+      @token_expires_at = nil
+      @location_id = nil
+      @delegation_token = nil
+    end
+
+    def initialize_serialized(data)
+      @token_expires_at = Time.at(data['token_expires_at'].to_i)
+      @location_id = data['location_id']
+      @delegation_token = data['delegation_token']
+    end
+
+    def serializable_data
+      data = {}
+      data['token_expires_at'] = @token_expires_at.to_i if @token_expires_at
+      data['location_id'] = @location_id if @location_id
+      data['delegation_token'] = @delegation_token if @delegation_token
+      data
+    end
+
+    def authentication_url(target, options={})
+      if force_origin
+        context = target
+        target = force_origin + URI.parse(target).path
+      end
+
+      url = "https://consent.live.com/Delegation.aspx"
+      query = {
+        'ps' => 'Contacts.Invite',
+        'ru' => target,
+        'pl' => privacy_policy_url,
+        'app' => app_verifier,
+      }
+      query['appctx'] = context if context
+      "#{url}?#{params_to_query(query)}"
+    end
+
+    def forced_redirect_url(params)
+      target_origin = params['appctx'] and
+        "#{target_origin}?#{params_to_query(params)}"
+    end
+
+    def authorize(params)
+      consent_token_data = params['ConsentToken'] or
+        raise Error, "no ConsentToken from Windows Live"
+      eact = backwards_query_to_params(consent_token_data)['eact'] or
+        raise Error, "missing eact from Windows Live"
+      query = decode_eact(eact)
+      consent_authentic?(query) or
+        raise Error, "inauthentic Windows Live consent"
+      params = query_to_params(query)
+      @token_expires_at = Time.at(params['exp'].to_i)
+      @location_id = params['lid']
+      @delegation_token = params['delt']
+      true
+    rescue Error => error
+      @error = error.message
+      false
+    end
+
+    def contacts(options={})
+      return nil if @delegation_token.nil? || @token_expires_at < Time.now
+      # TODO: Handle expired token.
+      xml = request_contacts
+      parse_xml(xml)
+    end
+
+    private
+
+    def signature_key
+      OpenSSL::Digest::SHA256.digest("SIGNATURE#{secret_key}")[0...16]
+    end
+
+    def encryption_key
+      OpenSSL::Digest::SHA256.digest("ENCRYPTION#{secret_key}")[0...16]
+    end
+
+    def app_verifier
+      token = params_to_query({
+        'appid' => application_id,
+        'ts' => Time.now.to_i,
+      })
+      token << "&sig=#{CGI.escape(Base64.encode64(sign(token)))}"
+    end
+
+    def sign(token)
+      OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, signature_key, token)
+    end
+
+    def decode_eact(eact)
+      token = Base64.decode64(CGI.unescape(eact))
+      iv, crypted = token[0...16], token[16..-1]
+      cipher = OpenSSL::Cipher::AES128.new("CBC")
+      cipher.decrypt
+      cipher.iv = iv
+      cipher.key = encryption_key
+      cipher.update(crypted) + cipher.final
+    end
+
+    def consent_authentic?(query)
+      body, encoded_signature = query.split(/&sig=/)
+      signature = Base64.decode64(CGI.unescape(encoded_signature))
+      sign(body) == signature
+    end
+
+    #
+    # Like #query_to_params, but do the unescaping *before* the
+    # splitting on '&' and '=', like Microsoft does it.
+    #
+    def backwards_query_to_params(data)
+      params={}
+      CGI.unescape(data).split(/&/).each do |pair|
+        key, value = *pair.split(/=/)
+        params[key] = value ? value : ''
+      end
+      params
+    end
+
+    def request_contacts
+      http = Net::HTTP.new('livecontacts.services.live.com', 443)
+      http.use_ssl = true
+      url = "/users/@L@#{@location_id}/rest/invitationsbyemail"
+      authorization = "DelegatedToken dt=\"#{@delegation_token}\""
+      http.get(url, {"Authorization" => authorization}).body
+    end
+
+    def parse_xml(xml)
+      document = Nokogiri::XML(xml)
+      document.search('/LiveContacts/Contacts/Contact').map do |contact|
+        email = contact.at('PreferredEmail').inner_text.strip
+        names = []
+        element = contact.at('Profiles/Personal/FirstName') and
+          names << element.inner_text.strip
+        element = contact.at('Profiles/Personal/LastName') and
+          names << element.inner_text.strip
+        Contact.new(email, names.join(' '))
+      end
+    end
+  end
+end