ruby-openid 1.1.4 → 2.0.1

data/lib/openid/consumer.rb

@@ -1,120 +1,124 @@
-require "uri"
+require "openid/consumer/idres.rb"
+require "openid/consumer/checkid_request.rb"
+require "openid/consumer/associationmanager.rb"
+require "openid/consumer/responses.rb"
+require "openid/consumer/discovery_manager"
+require "openid/consumer/discovery"
+require "openid/message"
+require "openid/yadis/discovery"
+require "openid/store/nonce"
 
-require "openid/util"
-require "openid/dh"
-require "openid/fetchers"
-require "openid/association"
-require "openid/discovery"
-
-
-# Everything in this library exists within the OpenID Module.  Users of
-# the library should look at OpenID::Consumer and/or OpenID::Server
 module OpenID
-
-  # ==Overview
+  # OpenID support for Relying Parties (aka Consumers).
   #
-  # Brief terminology:
+  # This module documents the main interface with the OpenID consumer
+  # library.  The only part of the library which has to be used and
+  # isn't documented in full here is the store required to create an
+  # Consumer instance.
   #
-  # [+Consumer+]
-  #   The website wanting to verify an OpenID identity URL.  Sometimes
-  #   called a "relying party".  If you want people to log into your site
-  #   using OpenID, then you are the consumer.
-  # 
-  # [+Server+]
-  #   The website which makes assertions as to whether or not the user
-  #   at the end of the browser owns the URL they say they do.
+  # = OVERVIEW
   #
-  # [+Redirect+]
-  #   An HTTP 302 (Temporarily Moved) redirect.  When issued as an HTTP
-  #   response from the server, the browser changes it's location to the
-  #   value specified.
-  #
-  # The OpenID authentication process requires the following steps,
-  # as visible to the user of this library:
+  # The OpenID identity verification process most commonly uses the
+  # following steps, as visible to the user of this library:
   #
   # 1. The user enters their OpenID into a field on the consumer's
   #    site, and hits a login button.
   #
-  # 2. The consumer site discovers the user's OpenID server information using
-  #    the Yadis protocol (Potentially falling back to OpenID 1.0 "linkrel"
-  #    discovery).
+  # 2. The consumer site discovers the user's OpenID provider using
+  #    the Yadis protocol.
   #
-  # 3. The consumer site prepares a URL to be sent to the  server
-  #    which contains the OpenID autentication information, and 
-  #    issues a redirect user's browser.
+  # 3. The consumer site sends the browser a redirect to the OpenID
+  #    provider.  This is the authentication request as described in
+  #    the OpenID specification.
   #
-  # 4. The server then verifies that the user owns the URL
-  #    provided, and sends the browser a redirect
-  #    back to the consumer.  This redirect contains the
-  #    server's response to the authentication request.
+  # 4. The OpenID provider's site sends the browser a redirect back to
+  #    the consumer site.  This redirect contains the provider's
+  #    response to the authentication request.
   #
   # The most important part of the flow to note is the consumer's site
   # must handle two separate HTTP requests in order to perform the
-  # full identity check.  These two HTTP requests are described in
-  # steps 1 and 4 above, and are handled by Consumer.begin and
-  # Consumer.complete respectively.
-  #
+  # full identity check.
   #
-  # ==Consumer Library Design
+  # = LIBRARY DESIGN
   #
-  # The library is designed with the above flow in mind.  The
+  # This consumer library is designed with that flow in mind.  The
   # goal is to make it as easy as possible to perform the above steps
   # securely.
   #
   # At a high level, there are two important parts in the consumer
-  # library.  The first important part is the OpenID::Consumer class,
-  # which contains the public interface to the consumer logic.
-  # The second is the OpenID::Store class, which defines the
-  # interface needed to store the state the consumer needs to maintain
-  # between requests.
+  # library.  The first important part is this module, which contains
+  # the interface to actually use this library.  The second is
+  # openid/store/interface.rb, which describes the interface to use if
+  # you need to create a custom method for storing the state this
+  # library needs to maintain between requests.
   #
   # In general, the second part is less important for users of the
-  # library to know about, as several concrete store implementations are
-  # provided.  The user simply needs to choose the store which best fits
-  # their environment and requirements.
-  #
-  #
-  # ==Stores and Dumb Mode
-  #
-  # OpenID is a protocol that works best when the consumer site is
-  # able to store some state.  This is the normal mode of operation
-  # for the protocol, and is sometimes referred to as smart mode.
-  # There is also a fallback mode, known as dumb mode, which is
-  # available when the consumer site is not able to store state.  This
-  # mode should be avoided when possible, as it leaves the
-  # implementation more vulnerable to replay attacks.
-  #
-  # The mode the library works in for normal operation is determined
-  # by the store that it is given.  The store is an abstraction that
-  # handles the data that the consumer needs to manage between HTTP
-  # requests in order to operate efficiently and securely.
+  # library to know about, as several implementations are provided
+  # which cover a wide variety of situations in which consumers may
+  # use the library.
+  #
+  # The Consumer class has methods corresponding to the actions
+  # necessary in each of steps 2, 3, and 4 described in the overview.
+  # Use of this library should be as easy as creating an Consumer
+  # instance and calling the methods appropriate for the action the
+  # site wants to take.
+  #
+  # This library automatically detects which version of the OpenID
+  # protocol should be used for a transaction and constructs the
+  # proper requests and responses.  Users of this library do not need
+  # to worry about supporting multiple protocol versions; the library
+  # supports them implicitly.  Depending on the version of the
+  # protocol in use, the OpenID transaction may be more secure.  See
+  # the OpenID specifications for more information.
+  #
+  # = SESSIONS, STORES, AND STATELESS MODE
+  #
+  # The Consumer object keeps track of two types of state:
+  #
+  # 1. State of the user's current authentication attempt.  Things
+  #    like the identity URL, the list of endpoints discovered for
+  #    that URL, and in case where some endpoints are unreachable, the
+  #    list of endpoints already tried.  This state needs to be held
+  #    from Consumer.begin() to Consumer.complete(), but it is only
+  #    applicable to a single session with a single user agent, and at
+  #    the end of the authentication process (i.e. when an OP replies
+  #    with either <tt>id_res</tt>. or <tt>cancel</tt> it may be
+  #    discarded.
+  #
+  # 2. State of relationships with servers, i.e. shared secrets
+  #    (associations) with servers and nonces seen on signed messages.
+  #    This information should persist from one session to the next
+  #    and should not be bound to a particular user-agent.
+  #
+  # These two types of storage are reflected in the first two
+  # arguments of Consumer's constructor, <tt>session</tt> and
+  # <tt>store</tt>.  <tt>session</tt> is a dict-like object and we
+  # hope your web framework provides you with one of these bound to
+  # the user agent.  <tt>store</tt> is an instance of Store.
+  #
+  # Since the store does hold secrets shared between your application
+  # and the OpenID provider, you should be careful about how you use
+  # it in a shared hosting environment.  If the filesystem or database
+  # permissions of your web host allow strangers to read from them, do
+  # not store your data there!  If you have no safe place to store
+  # your data, construct your consumer with nil for the store, and it
+  # will operate only in stateless mode.  Stateless mode may be
+  # slower, put more load on the OpenID provider, and trusts the
+  # provider to keep you safe from replay attacks.
   #
   # Several store implementation are provided, and the interface is
-  # fully documented so that custom stores can be used as well. The
-  # implementations that are provided allow the consumer site to store
-  # data in a couple of different ways: in the filesystem,
-  # or in an SQL database.
-  #
-  # There is an additional concrete store provided that puts the
-  # consumer in dumb mode.  This is not recommended, as it removes the
-  # library's ability to stop replay attacks reliably.  It still uses
-  # time-based checking to make replay attacks only possible within a
-  # small window, but they remain possible within that window.  This
-  # store should only be used if the consumer site has no way to
-  # retain data between requests at all. See DumbStore for more info.
-  #
-  # If your ennvironment permits, use of the FilesystemStore
-  # is recommended.
-  #
-  #
-  # ==Immediate Mode
-  #
-  # If you are new to OpenID, it is suggested that you skip this section
-  # and refer to it later.  Immediate mode is an advanced consumer topic.
-  #
-  # In the flow described in the overview, the user may need to confirm to the
-  # identity server that it's ok to authorize his or her identity.
-  # The server may draw pages asking for information from the user
+  # fully documented so that custom stores can be used as well.  See
+  # the documentation for the Consumer class for more information on
+  # the interface for stores.  The implementations that are provided
+  # allow the consumer site to store the necessary data in several
+  # different ways, including several SQL databases and normal files
+  # on disk.
+  #
+  # = IMMEDIATE MODE
+  #
+  # In the flow described above, the user may need to confirm to the
+  # OpenID provider that it's ok to disclose his or her identity.  The
+  # provider may draw pages asking for information from the user
   # before it redirects the browser back to the consumer's site.  This
   # is generally transparent to the consumer site, so it is typically
   # ignored as an implementation detail.
@@ -124,794 +128,263 @@ module OpenID
   # put the library in immediate mode.  In immediate mode, there is an
   # extra response possible from the server, which is essentially the
   # server reporting that it doesn't have enough information to answer
-  # the question yet.  In addition to saying that, the identity server
-  # provides a URL to which the user can be sent to provide the needed
-  # information and let the server finish handling the original
-  # request.
-  #
-  # You may invoke immediate mode when building the redirect URL to the
-  # OpenID server in the SuccessRequest.redirect_url method.  Pass true
-  # for the +immediate+ paramter.  Read the interface for Consumer.complete
-  # for information about handling the additional response.
+  # the question yet.
   #
-  # ==Using the Library
+  # = USING THIS LIBRARY
   #
-  # Integrating this library into an application is a
-  # relatively straightforward process.  The process usually follows this plan:
+  # Integrating this library into an application is usually a
+  # relatively straightforward process.  The process should basically
+  # follow this plan:
   #
   # Add an OpenID login field somewhere on your site.  When an OpenID
   # is entered in that field and the form is submitted, it should make
-  # a request to the site which includes that OpenID URL.
-  #
-  # When your site receives that request, it should create an
-  # OpenID::Consumer instance, and call
-  # OpenID::Consumer.begin.  If begin completes successfully,
-  # it will return a SuccessRequest object.  Otherwise it will subclass
-  # of OpenIDStatus which contains additional information about the
-  # the failure.
-  #
-  # If successful, build a redirect URL to the server by calling
-  # SuccessRequest.redirect_url and send back an HTTP 302 redirect
-  # of that URL to the user's browser. The redirect_url accepts a 
-  # return_to parameter, which is the URL to which they will return
-  # to fininsh the OpenID transaction.  This URL is supplied by you,
-  # and should be able to handle step 4 of the flow described in the
-  # overview.
+  # a request to the your site which includes that OpenID URL.
+  #
+  # First, the application should instantiate a Consumer with a
+  # session for per-user state and store for shared state using the
+  # store of choice.
+  #
+  # Next, the application should call the <tt>begin</tt> method of
+  # Consumer instance.  This method takes the OpenID URL as entered by
+  # the user.  The <tt>begin</tt> method returns a CheckIDRequest
+  # object.
+  #
+  # Next, the application should call the redirect_url method on the
+  # CheckIDRequest object.  The parameter <tt>return_to</tt> is the
+  # URL that the OpenID server will send the user back to after
+  # attempting to verify his or her identity.  The <tt>realm</tt>
+  # parameter is the URL (or URL pattern) that identifies your web
+  # site to the user when he or she is authorizing it.  Send a
+  # redirect to the resulting URL to the user's browser.
   #
   # That's the first half of the authentication process.  The second
-  # half of the process is done after the OpenID server sends the
-  # user's browser a redirect back to your site with the
-  # authentication response.
-  #
-  # When that happens, the browser will make a request to the return_to
-  # URL you provided to the SuccessRequest.redirect_url
-  # method.  The request will have several query parameters added
-  # to the URL by the identity server as the information necessary to
+  # half of the process is done after the user's OpenID Provider sends
+  # the user's browser a redirect back to your site to complete their
+  # login.
+  #
+  # When that happens, the user will contact your site at the URL
+  # given as the <tt>return_to</tt> URL to the redirect_url call made
+  # above.  The request will have several query parameters added to
+  # the URL by the OpenID provider as the information necessary to
   # finish the request.
   #
-  # Your job here is to make sure that the action performed at the return_to
-  # URL creates an instnce of OpenID::Consumer, and calls the Consumer.complete
-  # method. This call will
-  # return a SuccessResponse object, or a subclass of OpenIDStatus explaining,
-  # the failure.  See the documentation for Consumer.complete
-  # for a full explanation of the possible responses.
+  # Get a Consumer instance with the same session and store as before
+  # and call its complete() method, passing in all the received query
+  # arguments and the <tt>return_to</tt> URL mentioned above.
   #
-  # If you received a SuccessResponse, you may access the identity URL
-  # of the user though it's +identity_url+ method.
+  # There are multiple possible return types possible from that
+  # method. These indicate the whether or not the login was
+  # successful, and include any additional information appropriate for
+  # their type.
   class Consumer
-    
-    @@service_key = '_openid_consumer_service'
-    @@disco_suffix = 'xopenid_services'
-    attr_accessor :consumer, :session, :fetcher
+    attr_accessor :session_key_prefix
 
-    # Creates a new OpenID::Consumer instance.  You should create a new
-    # instance of the Consumer object with every HTTP request that handles
-    # OpenID transactions.  Do not store the instance of it in a
-    # global variable somewhere.
+    # Initialize a Consumer instance.
+    #
+    # You should create a new instance of the Consumer object with
+    # every HTTP request that handles OpenID transactions.
     #
-    # [+session+]
-    #   A hash-like object representing the user's session data.  This is
-    #   used for keeping state of the OpenID transaction when the user is
-    #   redirected to the server.  In a rails application, the controller's
-    #   @session instance variable should be used.
+    # session: the session object to use to store request information.
+    # The session should behave like a hash.
     #
-    # [+store+] 
-    #   This must be an object that implements the OpenID::Store interface.
-    #   Several concrete implementations are provided, to cover
-    #   most common use cases.  We recommend using the simple file based
-    #   store bundled with the library: OpenID::FilesystemStore.
-    # 
-    # [+fetcher+]
-    #   Optional.  If provided, this must be an instance that implements
-    #   OpenID::Fetcher interface.  If no fetcher is provided,
-    #   an OpenID::StandardFetcher instance will be created
-    #   for you automatically.  If you need custom fetcher behavior, it
-    #   is probably best to subclass StandardFetcher, and pass your instance
-    #   in here.
-    # 
-    # This object keeps an internal instance of OpenID::GenericConsumer
-    # for low level OpenID calls, called +consumer+. You may use a custom    
-    # certificate authority PEM file for veryifying HTTPS server certs
-    # by calling the GenericConsumer.ca_path= method of the +consumer+
-    # instance variable.
-    def initialize(session, store, fetcher=nil)
+    # store: an object that implements the interface in Store.
+    def initialize(session, store)
       @session = session
-      @consumer = GenericConsumer.new(store, fetcher)
+      @store = store
+      @session_key_prefix = 'OpenID::Consumer::'
     end
 
-    # +begin+ is called to start the OpenID verification process.  See steps
-    # 1-2 in the overview at the top of this file.
-    #
-    # ==Parameters
-    #
-    # [+user_url+]
-    #   Identity URL given by the user. +begin+ performs a textual
-    #   transformation of the URL to try and make sure it is "normalized",
-    #   for example, a user_url of example.com will be normalized to
-    #   http://example.com/ normalizing and resolving any redirects
-    #   the server might issue.
+    # Start the OpenID authentication process. See steps 1-2 in the
+    # overview for the Consumer class.
     #
-    # ==Return Value
+    # user_url: Identity URL given by the user. This method performs a
+    # textual transformation of the URL to try and make sure it is
+    # normalized. For example, a user_url of example.com will be
+    # normalized to http://example.com/ normalizing and resolving any
+    # redirects the server might issue.
     #
-    # +begin+ returns a subclass of OpenIDStatus, which is an object
-    # that has a +status+ method.  The status methodfor this object will either
-    # return OpenID::SUCCESS, or OpenID::FAILURE.  Generally +begin+ will fail
-    # if the users' OpenID page cannot be retrieved or OpenID server
-    # information cannot be determined.
-    # 
-    # ===Success
+    # anonymous: A boolean value.  Whether to make an anonymous
+    # request of the OpenID provider.  Such a request does not ask for
+    # an authorization assertion for an OpenID identifier, but may be
+    # used with extensions to pass other data.  e.g. "I don't care who
+    # you are, but I'd like to know your time zone."
     #
-    # In the case that request.status equals OpenID::SUCCESS, the response
-    # will be of type OpenID::SuccessRequest.  The SuccessRequest object
-    # may the be used to add simple registration extension arguments,
-    # using SuccessRequest.add_extension_arg, and build the redirect
-    # url to the server using SuccessRequest.redirect_url as described
-    # in step 3 of the overview.
+    # Returns a CheckIDRequest object containing the discovered
+    # information, with a method for building a redirect URL to the
+    # server, as described in step 3 of the overview. This object may
+    # also be used to add extension arguments to the request, using
+    # its add_extension_arg method.
     #
-    # The next step in the success case is to actually build the redirect
-    # URL to the server.  Please see the documentation for
-    # SuccessRequest.redirect_url for details.  Once the redirect url
-    # is created, you should issue an HTTP 302 temporary redirect to the
-    # user's browser, sending her to the OpenID server.  Once the user
-    # finishes the operations on the server, she will be redirected back to
-    # the return_to URL you passed to redirect_url, which should invoke
-    # the Consumer.complete method.
-    #
-    # ===Failure
-    # 
-    # If the library is unable to fetch the +user_url+, or no server
-    # information can be determined, or if the server information is malformed,
-    # +begin+ will return a FailureRequest object.  The status method of this
-    # object will return OpenID::FAILURE.  FailureRequest objects have a
-    # +msg+ method which provides more detailed information as to why
-    # the request failed.
-    def begin(user_url)
-      discovery = self.get_discovery(user_url)
-
-      unless discovery
-        return FailureRequest.new("Don't know how to find services for that identifier")
-      end
-
-      service = discovery.next_service
+    # Raises DiscoveryFailure when no OpenID server can be found for
+    # this URL.
+    def begin(openid_identifier, anonymous=false)
+      manager = discovery_manager(openid_identifier)
+      service = manager.get_next_service(&method(:discover))
 
-      unless service
-        return FailureRequest.new('No service endpoints found.')
+      if service.nil?
+        raise DiscoveryFailure.new("No usable OpenID services were found "\
+                                   "for #{openid_identifier.inspect}", nil)
+      else
+        begin_without_discovery(service, anonymous)
       end
-      
-      return self.begin_without_discovery(service)
     end
 
-    # Start the OpenID transaction without doing OpenID server
-    # discovery. This method is used internally by Consumer.begin after
-    # discovery is performed, and exists to provide an interface for library
-    # users needing to perform their own discovery.
-    #
-    # ==Parameters
+    # Start OpenID verification without doing OpenID server
+    # discovery. This method is used internally by Consumer.begin()
+    # after discovery is performed, and exists to provide an interface
+    # for library users needing to perform their own discovery.
     #
-    # +service+ must be an OpenID::OpenIDServiceEnpoint object, or an object
-    # that implements it's interface.  You may produce these objects
-    # and perform discovery manually using OpenID::OpenIDDiscovery.
+    # service: an OpenID service endpoint descriptor.  This object and
+    # factories for it are found in the openid/consumer/discovery.rb
+    # module.
     #
-    # ==Return Value
-    # 
-    # +begin_without_discovery+ always returns an OpenID::SuccessRequest
-    # object.  Please see the success documentation for OpenID::Consumer.begin
-    # for more information.
-    def begin_without_discovery(service)
-      request = @consumer.begin(service)
-      @session[@@service_key] = service
-      return request
+    # Returns an OpenID authentication request object.
+    def begin_without_discovery(service, anonymous)
+      assoc = association_manager(service).get_association
+      checkid_request = CheckIDRequest.new(assoc, service)
+      checkid_request.anonymous = anonymous
+
+      if service.compatibility_mode
+        rt_args = checkid_request.return_to_args
+        rt_args[Consumer.openid1_return_to_nonce_name] = Nonce.mk_nonce
+        rt_args[Consumer.openid1_return_to_claimed_id_name] =
+          service.claimed_id
+      end
+
+      self.last_requested_endpoint = service
+      return checkid_request
     end
-    
-    # Called to interpret the server's response to an OpenID request. It
-    # is called in step 4 of the flow described in the consumer overview.
-    #
-    # ==Parameters
-    # [+query+]
-    #   A hash of the query paramters for this HTTP request.
-    #
-    # ==Return Value
-    # Return value is a subclass of OpenIDStatus, and may have a status
-    # of OpenID::SUCCESS, OpenID::CANCEL, OpenID::FAILURE,
-    # or OpenID::SETUP_NEEDED.  The status may be accessed through the
-    # +status+ method of the response object.
-    #
-    # When OpenID::SUCCESS is returned, the response object will be of 
-    # type SuccessResponse, which has several useful attributes including
-    # +identity_url+, +service+, and a method +extension_response+ for
-    # extracting potential signed extension reponses from the server.  See
-    # the documentation for OpenID::SuccessResponse for more information
-    # about it's interface and methods.
+
+    # Called to interpret the server's response to an OpenID
+    # request. It is called in step 4 of the flow described in the
+    # Consumer overview.
     #
-    # In the case of response.status being OpenID::CANCEL, the user cancelled
-    # the OpenID transaction on the server. The response will be an instance
-    # of OpenID::CancelResponse, and you may access the originally submitted
-    # identity URL and service information through that object.
+    # query: A hash of the query parameters for this HTTP request.
+    # Note that in rails, this is <b>not</b> <tt>params</tt> but
+    # <tt>params.reject{|k,v|request.path_parameters[k]}</tt>
+    # because <tt>controller</tt> and <tt>action</tt> and other
+    # "path parameters" are included in params.
     #
-    # When status is OpenID::FAILURE, the object will be an instance of
-    # OpenID::FailureResponse. If the identity which failed can be determined
-    # it will be available by accessing the +identity_url+ attribute of the
-    # response.  FailureResponse objects also have a +msg+ attribute
-    # which may be useful in debugging.  If no msg is specified, msg will be
-    # nil.
+    # return_to: The return URL used to invoke the application.
+    # Extract the URL from your application's web request framework
+    # and specify it here to have it checked against the
+    # openid.return_to value in the response.  If the return_to URL
+    # check fails, the status of the completion will be FAILURE.
     #
-    # When OpenID::SETUP_NEEDED is returned, the response object is an 
-    # instance of OpenID::SetupNeededResponse. The useful piece of information
-    # contained in this response is the +setup_url+ method, which
-    # should be used to send the user to the server and log in.
-    # This response is only generated by immediate
-    # mode requests (openid.mode=immediate).  The user should be redirected
-    # in to the +setup_url+, either in the current window or in a 
-    # new browser window.
-    def complete(query)
-      service = @session[@@service_key]
-      
-      if service.nil?
-        resp = FailureResponse.new(nil, 'No session state found.')
-      else
-        resp = @consumer.complete(query, service)
+    # Returns a subclass of Response. The type of response is
+    # indicated by the status attribute, which will be one of
+    # SUCCESS, CANCEL, FAILURE, or SETUP_NEEDED.
+    def complete(query, return_to)
+      message = Message.from_post_args(query)
+      mode = message.get_arg(OPENID_NS, 'mode', 'invalid')
+      begin
+        meth = method('complete_' + mode)
+      rescue NameError
+        meth = method(:complete_invalid)
       end
-
-      # If the response has an non-nil identity_url attribute,
-      # then we can get te discovery object and finalize the request.
-      # Otherwise it is a failure or replay, and we set the response
-      # servce to nil.
-      if resp.identity_url
-        disco = self.get_discovery(resp.identity_url)
-        if [SUCCESS, CANCEL].member?(resp.status)
-          if resp.identity_url
-            resp.service = disco.finish
-          end
-        else
-          resp.service = disco.current
-        end
-      else
-        resp.service = nil
+      response = meth.call(message, return_to)
+      cleanup_last_requested_endpoint
+      if [SUCCESS, CANCEL].member?(response.status)
+        cleanup_session
       end
-
-
-      # want to delete service unless status is SETUP_NEEDED,
-      # because we still need the service info when the user returns from
-      # the server
-      unless resp.status == SETUP_NEEDED
-        @session[@@service_key] = nil
-      end
-
-      return resp
+      return response
     end
 
     protected
-    
-    # Used internally to create an instnace of the OpenIDDiscovery object.
-    def get_discovery(url)
-      if XRI::identifier_scheme(url) == :xri
-        XRIDiscovery.new(@session, url, @@disco_suffix)
-      else
-        url = OpenID::Util.normalize_url(url)
-        if url
-          user_url = user_url.to_s
-          OpenIDDiscovery.new(@session, url, @consumer.fetcher, @@disco_suffix)
-        else
-          nil
-        end
-      end
-    end
-  end
 
-  # This class implements the common logic for OpenID consumers.  It
-  # is used by the higher level OpenID::Consumer class.  Only advanced
-  # users with special needs should ever have to look at this class.
-  #
-  # The only part of the library which has to be used and isn't
-  # documented in full here is the store required to create an
-  # OpenID::Consumer instance.  More on the abstract store type and
-  # concrete implementations of it that are provided in the documentation
-  # of OpenID::Consumer.new 
-  class GenericConsumer
-
-    # Number of characters to be used in generated nonces
-    @@NONCE_LEN = 8
-    
-    # Nonce character set
-    @@NONCE_CHRS = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
-    @@D_SUFFIX = 'openid_disco'
-
-    attr_reader :fetcher
-
-    public
-        
-    # Creates a new Consumer instance.  You should create a new
-    # instance of the Consumer object with every HTTP request.  Do not
-    # store the instance of it in a global variable somewhere.
-    #
-    # [+store+] 
-    #   This must be an object that implements the OpenID::Store interface.
-    #   Several concrete implementations are provided, to cover
-    #   most common use cases.  We recommend using the simple file based
-    #   store bundled with the library: OpenID::FilesystemStore.
-    # 
-    # [+fetcher+]
-    #   Optional.  If provided, this must be an instance that implements
-    #   Fetcher interface.  If no fetcher is provided,
-    #   an instance of OpenID::StandardFetcher will be created for
-    #   you automatically.
-    def initialize(store, fetcher=nil)
-      if fetcher.nil?
-        fetcher = StandardFetcher.new
-      end
-      @store = store
-      @fetcher = fetcher
-      @ca_path = nil
-    end
-    
-    # Set the path to a pem certificate authority file for verifying
-    # server certificates during HTTPS.  If you are interested in verifying
-    # certs like the mozilla web browser, have a look at the files here:
-    #
-    # http://curl.haxx.se/docs/caextract.html
-    def ca_path=(ca_path)
-      ca_path = ca_path.to_s
-      if File.exists?(ca_path)
-        @ca_path = ca_path
-        @fetcher.ca_path = ca_path
-      else
-        raise ArgumentError, "#{ca_path} is not a valid file path"
-      end
+    def session_get(name)
+      @session[session_key(name)]
     end
 
-    # See the interface documentation for Consumer.begin_without_discovery
-    # for arugumnets and return values of this method.
-    # begin_without_discovery is a light wrapper around this method, and the
-    # has the same interface.
-    def begin(service)
-      nonce = self.create_nonce
-      assoc = self.get_association(service.server_url)
-      return SuccessRequest.new(assoc, nonce, service)
+    def session_set(name, val)
+      @session[session_key(name)] = val
     end
 
-    # Please see the interface docs for Consumer.complete.  This method accpets
-    # a +service+ paramter which is provided though the SuccessRequest object
-    # generated in the +begin+ call.  The +service+ should be stored somewhere
-    # in the user's session or environment and passed into this method
-    # along with the full query string Hash.  Consumer.complete has the
-    # full list of return values for this method.
-    def complete(query, service_endpoint)
-      return FailureResponse.new(nil, msg='no session state found') unless service_endpoint
-
-      consumer_id = service_endpoint.consumer_id
-      server_id = service_endpoint.server_id
-      server_url = service_endpoint.server_url
-
-      # get the nonce out of the query
-      nonce = query['nonce']
-      if nonce.nil?
-        return FailureResponse.new(consumer_id, 'could not extract nonce')
-      end
-
-      mode = query["openid.mode"]
-
-      case mode
-      when "cancel"        
-        return CancelResponse.new(consumer_id)
-
-      when "error"
-        error = query["openid.error"]
-        unless error.nil?
-          OpenID::Util.log('Error: '+error)
-        end
-        return FailureResponse.new(nil, msg=error)
-
-      when "id_res"        
-        return self.do_id_res(nonce, consumer_id, server_id, server_url, query)
-
-      else
-        return FailureResponse.new(nil, msg="unknown mode #{mode}")
-      end
-
+    def session_key(suffix)
+      @session_key_prefix + suffix
     end
 
-    # Low level method for handling the OpenID server response.
-    def do_id_res(nonce, consumer_id, server_id, server_url, query)
-      user_setup_url = query["openid.user_setup_url"]
-      if user_setup_url
-        return SetupNeededResponse.new(user_setup_url)
-      end
-      
-      return_to = query["openid.return_to"]
-      server_id2 = query["openid.identity"]
-      assoc_handle = query["openid.assoc_handle"]
-      
-      if return_to.nil?
-        return FailureResponse.new(consumer_id, msg='openid.return_to was nil')
-      elsif server_id2.nil?
-        return FailureResponse.new(consumer_id, msg='openid.identity was nil')
-      elsif assoc_handle.nil?
-        return FailureResponse.new(consumer_id, msg='openid.assoc_handle was nil')
-      end
-      
-      if server_id != server_id2
-        return FailureResponse.new(consumer_id, msg='server ids do not match')
-      end
-      
-      assoc = @store.get_association(server_url, assoc_handle)
-    
-      if assoc.nil?
-        # It's not an association we know about. Dumb mode is our
-        # only possible path for recovery.
-        code, msg = self.check_auth(nonce, query, server_url)
-        if code == SUCCESS
-          return SuccessResponse.new(consumer_id, query)
-        else
-          return FailureResponse.new(consumer_id, "check_auth failed: #{msg}")
-        end
-      end
-
-      if assoc.expires_in <= 0
-        OpenID::Util.log("Association with #{server_url} expired")
-        return FailureResponse.new(consumer_id, 'assoc expired')
-      end
-
-      # Check the signature
-      sig = query["openid.sig"]
-      return FailureResponse.new(consumer_id, 'no sig') if sig.nil?
-      signed = query["openid.signed"]
-      return FailureResponse.new(consumer_id, 'no signed') if signed.nil?
-      
-      args = OpenID::Util.get_openid_params(query)
-      signed_list = signed.split(",")
-      _signed, v_sig = OpenID::Util.sign_reply(args, assoc.secret, signed_list)
-
-      if v_sig != sig
-        return FailureResponse.new(consumer_id, 'sig mismatch')
-      end
-
-      unless @store.use_nonce(nonce)
-        return FailureResponse.new(consumer_id, 'nonce already used')
-      end
-
-      return SuccessResponse.new(consumer_id, query)
+    def last_requested_endpoint
+      session_get('last_requested_endpoint')
     end
 
-    # Low level method for performing OpenID check_authenticaion requests
-    def check_auth(nonce, query, server_url)
-      check_args = OpenID::Util.get_openid_params(query)
-      check_args["openid.mode"] = "check_authentication"
-      post_data = OpenID::Util.urlencode(check_args)
-
-      ret = @fetcher.post(server_url, post_data)
-      if ret.nil?
-        return FAILURE, "unable to post to #{server_url}"
-      else
-        url, body = ret
-      end
-    
-      results = OpenID::Util.parsekv(body)
-      is_valid = results.fetch("is_valid", "false")
-    
-      if is_valid == "true"
-
-        # we started this request with a bad association,
-        # falling back to dumb mode, the invalidate_handle tells
-        # us to handle of the assoc to remove from our store.
-        invalidate_handle = results["invalidate_handle"]
-        if invalidate_handle
-          @store.remove_association(server_url, invalidate_handle)
-        end
-
-        # make sure response is not getting replayed by checking the nonce
-        unless @store.use_nonce(nonce)
-          return FAILURE, "#{server_url}, nonce #{nonce} already used"
-        end
-
-        # is_valid = true, and we successfully used the nonce.
-        return SUCCESS, nil
-      end
-    
-      error = results["error"]
-      if error
-        msg = "error from server: #{error}"
-      else
-        msg = "is_valid was false"
-      end
-      return FAILURE, msg
+    def last_requested_endpoint=(endpoint)
+      session_set('last_requested_endpoint', endpoint)
     end
 
-    # Create a nonce and store it for preventing replace attacks.
-    def create_nonce
-      # build the nonce and store it
-      nonce = OpenID::Util.random_string(@@NONCE_LEN, @@NONCE_CHRS)
-      @store.store_nonce(nonce)
-      return nonce
+    def cleanup_last_requested_endpoint
+      @session[session_key('last_requested_endpoint')] = nil
     end
 
-    # Get existing or create a new association (shared secret) with the
-    # server at +server_url+.
-    def get_association(server_url)
-      return nil if @store.dumb?
-      assoc = @store.get_association(server_url)
-      return assoc unless assoc.nil?
-      return self.associate(server_url)    
+    def discovery_manager(openid_identifier)
+      DiscoveryManager.new(@session, openid_identifier, @session_key_prefix)
     end
-    
-    # Make the openid.associate call to the server.
-    def associate(server_url)
-      dh = OpenID::DiffieHellman.new
-      cpub = OpenID::Util.to_base64(OpenID::Util.num_to_str(dh.public))
-      args = {
-        'openid.mode' => 'associate',
-        'openid.assoc_type' =>'HMAC-SHA1',
-        'openid.session_type' =>'DH-SHA1',
-        'openid.dh_modulus' => OpenID::Util.to_base64(OpenID::Util.num_to_str(dh.p)),
-        'openid.dh_gen' => OpenID::Util.to_base64(OpenID::Util.num_to_str(dh.g)),
-        'openid.dh_consumer_public' => cpub
-      }
-      body = OpenID::Util.urlencode(args)
-      
-      ret = @fetcher.post(server_url, body)
-      return nil if ret.nil?
-      url, data = ret
-      results = OpenID::Util.parsekv(data)
-      
-      assoc_type = results["assoc_type"]
-      return nil if assoc_type.nil? or assoc_type != "HMAC-SHA1"
-      
-      assoc_handle = results["assoc_handle"]
-      return nil if assoc_handle.nil?    
-      
-      expires_in = results.fetch("expires_in", "0").to_i
 
-      session_type = results["session_type"]
-      if session_type.nil?
-        secret = OpenID::Util.from_base64(results["mac_key"])
-      else
-        return nil if session_type != "DH-SHA1"
-        
-        dh_server_public = results["dh_server_public"]
-        return nil if dh_server_public.nil?
-        
-        spub = OpenID::Util.str_to_num(OpenID::Util.from_base64(dh_server_public))
-        dh_shared = dh.get_shared_secret(spub)
-        enc_mac_key = results["enc_mac_key"]
-        secret = OpenID::Util.strxor(OpenID::Util.from_base64(enc_mac_key),
-                                     OpenID::Util.sha1(OpenID::Util.num_to_str(dh_shared)))
-      end
-   
-      assoc = OpenID::Association.from_expires_in(expires_in, assoc_handle,
-                                                  secret, 'HMAC-SHA1')
-      @store.store_association(server_url, assoc)
-      return assoc
+    def cleanup_session
+      discovery_manager(nil).cleanup(true)
     end
 
-  end
-
-  # Base class for objects returned from Consumer.begin and Consumer.complete
-  class OpenIDStatus
-
-    attr_reader :status
 
-    def initialize(status)
-      @status = status
+    def discover(identifier)
+      OpenID.discover(identifier)
     end
 
-  end
-
-  # Returned by Consumer.begin when server information cannot be determined
-  # from the provided identity URL.  The +msg+ method may return a useful
-  # string for debugging the request.
-  class FailureRequest < OpenIDStatus
-
-    attr_reader :msg
-
-    def initialize(msg='')
-      super(FAILURE)
-      @msg = msg
+    def negotiator
+      DefaultNegotiator
     end
 
-  end
-
-  # Encapsulates the information the library retrieves and uses during
-  # Consumer.begin.
-  class SuccessRequest < OpenIDStatus
-    
-    attr_reader :server_id, :server_url, :nonce, :identity_url, \
-                :service, :return_to_args
-    
-    # Creates a new SuccessRequest object.  This just stores each
-    # argument in an appropriately named field.
-    #
-    # Users of this library should not create instances of this
-    # class.  Instances of this class are created by Consumer
-    # during begin.
-    def initialize(assoc, nonce, service)
-      super(SUCCESS)
-      @service = service
-      @server_id = service.server_id
-      @server_url = service.server_url
-      @identity_url = service.consumer_id
-      @extra_args = {}
-      @return_to_args = {'nonce' => nonce}
-
-      @assoc = assoc
-      @nonce = nonce
-    end
-
-    # Called to construct the redirect URL sent to
-    # the browser to ask the server to verify its identity.  This is
-    # called in step 3 of the flow described in the overview.
-    # Please note that you don't need to call this method directly
-    # unless you need to create a custom redirect, as it is called
-    # directly during begin. The generated redirect should be
-    # sent to the browser which initiated the authorization request.
-    #
-    # ==Parameters
-    # [+trust_root+]
-    #   This is a URL that will be sent to the
-    #   server to identify this site.  The OpenID spec (
-    #   http://www.openid.net/specs.bml#mode-checkid_immediate )
-    #   has more information on what the trust_root value is for
-    #   and what its form can be.  While the trust root is
-    #   officially optional in the OpenID specification, this
-    #   implementation requires that it be set.  Nothing is
-    #   actually gained by leaving out the trust root, as you can
-    #   get identical behavior by specifying the return_to URL as
-    #   the trust root.
-    #
-    # [+return_to+]
-    #   This is the URL that will be included in the
-    #   generated redirect as the URL the OpenID server will send
-    #   its response to.  The URL passed in must handle OpenID
-    #   authentication responses.
-    #
-    # [+immediate+]
-    #   Optional.  If +immediate+ is true, the request will be made using
-    #   openid.mode=checkid_immediate instead of the standard
-    #   openid.mode=checkid_setup. 
-    #
-    # ==Return Value
-    # Return a string which is the URL to which you should redirect the user.
-    def redirect_url(trust_root, return_to, immediate=false)
-      # add the nonce into the return_to url
-      return_to = OpenID::Util.append_args(return_to, @return_to_args)
-
-      redir_args = {
-        "openid.identity" => @server_id,
-        "openid.return_to" => return_to,
-        "openid.trust_root" => trust_root,
-        "openid.mode" => immediate ? 'checkid_immediate' : 'checkid_setup'
-      }
-
-      redir_args["openid.assoc_handle"] = @assoc.handle if @assoc
-      redir_args.update(@extra_args)
-     
-      return OpenID::Util.append_args(server_url, redir_args).to_s
+    def association_manager(service)
+      AssociationManager.new(@store, service.server_url,
+                             service.compatibility_mode, negotiator)
     end
 
-    # get the return_to URL
-    def return_to(return_to)
-      OpenID::Util.append_args(return_to, @return_to_args)
+    def handle_idres(message, return_to)
+      IdResHandler.new(message, return_to, @store, last_requested_endpoint)
     end
 
-    # Add an openid extension argument to the request. A simple resitration
-    # request may look something like:
-    #
-    #  req.add_extension_arg('sreg','required','email')
-    #  req.add_extension_arg('sreg','optional','nickname,gender')
-    #  req.add_extension_arg('sreg','policy_url','http://example.com/policy')
-    def add_extension_arg(namespace, key, value)
-      @extra_args['openid.'+namespace+'.'+key] = value
+    def complete_invalid(message, unused_return_to)
+      mode = message.get_arg(OPENID_NS, 'mode', '<No mode set>')
+      return FailureResponse.new(last_requested_endpoint,
+                                 "Invalid openid.mode: #{mode}")
     end
 
-    def add_arg(key, value)
-      @extra_args[key] = value
+    def complete_cancel(unused_message, unused_return_to)
+      return CancelResponse.new(last_requested_endpoint)
     end
 
-    # Checks to see if the user's OpenID server additionally supports
-    # the extensions service type url provided.
-    def uses_extension?(extension_url)
-      return false unless extension_url
+    def complete_error(message, unused_return_to)
+      error = message.get_arg(OPENID_NS, 'error')
+      contact = message.get_arg(OPENID_NS, 'contact')
+      reference = message.get_arg(OPENID_NS, 'reference')
 
-      @service.service_types.each do |url|
-        if OpenID::Util.urls_equal?(url, extension_url)
-          return true
-        end
-      end
-
-      return false
+      return FailureResponse.new(last_requested_endpoint,
+                                 error, contact, reference)
     end
 
-  end
-
-  # Encapsulates the information that is useful after a successful
-  # Consumer.complete call.  Verified identity URL and
-  # signed extension response values are available through this object.
-  class SuccessResponse < OpenIDStatus
-    
-    attr_reader :identity_url
-    attr_accessor :service
-
-    # Instances of this object will be created for you automatically
-    # by OpenID::Consumer.  You should never have to construct this
-    # object yourself.
-    def initialize(identity_url, query)
-      super(SUCCESS)
-      @identity_url = identity_url
-      @query = query
-      @service = nil
+    def complete_setup_needed(message, unused_return_to)
+      if message.is_openid1
+        return complete_invalid(message, nil)
+      else
+        return SetupNeededResponse.new(last_requested_endpoint, nil)
+      end
     end
 
-    # Returns all the arguments from an extension's namespace.  For example
-    # 
-    #   response.extension_response('sreg')
-    # 
-    # may return something like:
-    #
-    #  {'email' => 'mayor@example.com', 'nickname' => 'MayorMcCheese'}
-    #
-    # The extension namespace is not included in the keys of the returned
-    # hash.  Values returned from this method are guaranteed to be signed.
-    # Calling this method should be the *only* way you access extension
-    # response data!
-    def extension_response(extension_name)      
-      prefix = extension_name
-      
-      signed = @query['openid.signed']
-      return nil if signed.nil?
-      
-      signed = signed.split(',')
-      extension_args = {}
-      extension_prefix = prefix + '.'
-      
-      signed.each do |arg|
-        if arg.index(extension_prefix) == 0
-          query_key = 'openid.'+arg
-          extension_args[arg[(1+prefix.length..-1)]] = @query[query_key]
+    def complete_id_res(message, return_to)
+      if message.is_openid1
+        setup_url = message.get_arg(OPENID1_NS, 'user_setup_url')
+        if !setup_url.nil?
+          return SetupNeededResponse.new(last_requested_endpoint, setup_url)
         end
       end
-      
-      return extension_args
-    end
-
-  end
 
-  # Object returned from Consumer.complete when the auth request failed.
-  # The +identity_url+, +msg+, and +service+ methods may contain useful
-  # information about the failure if it is available.  These methods will
-  # return nil if no useful info can be determined.
-  class FailureResponse < OpenIDStatus
-    
-    attr_accessor :identity_url, :msg, :service
-
-    def initialize(identity_url=nil, msg=nil)
-      super(FAILURE)
-      @identity_url = identity_url
-      @msg = msg
-    end
-
-  end
-  
-  # Returned by Consumer.begin in immediate mode when the user needs to
-  # log into the OpenID server.  User should be redirected to the value
-  # returned from the +setup_url+ method.
-  class SetupNeededResponse < OpenIDStatus
-    
-    attr_reader :setup_url
-    attr_accessor :identity_url, :service
-
-    def initialize(setup_url)
-      super(SETUP_NEEDED)
-      @setup_url = setup_url
-    end
-
-  end
-
-  # Response returned from Consumer.complete when the user cancels the
-  # OpenID transaction.
-  class CancelResponse < OpenIDStatus
-    attr_accessor :identity_url, :service
-    def initialize(identity_url)
-      super(CANCEL)
-      @identity_url = identity_url
+      begin
+        idres = handle_idres(message, return_to)
+      rescue DiscoveryFailure, ProtocolError => why
+        return FailureResponse.new(last_requested_endpoint, why.message)
+      else
+        return SuccessResponse.new(idres.endpoint, message,
+                                     idres.signed_fields)
+      end
     end
   end
-
 end