Merge lp:~leonardr/launchpadlib/trusted-workflow into lp:launchpadlib

[Leonard Richardson]

[Leonard Richardson (leonardr)]

This branch introduces a generic engine for a trusted request-token-authorization client. I'm doing this because by and large, third-party developers aren't satisfied with opening the user's web browser and having them authorize a request token through the browser. They want a client that fits in with the rest of the UI. This generic engine can be used by command-line and GUI clients, and I've tested it by writing a scriptable client that implements stubs for all the plugin methods.

I have not written all the tests I'm going to write for this client, but I've written a representative sample, and I want to get what I have landed because this branch is getting kind of large.

There are two unrelated changes in this branch that I should have caught in my earlier branch (json-token-format):

1. I added launchpadlib/apps.py, which was written for the previous branch but I forgot to bzr add it. This contains the class tested by doc/command-line.txt.

2. A test in browser.txt was failing because of a bug in Launchpad. I filed a bug, hacked the test, and added a XXX.

[Edwin Grubbs (edwin-grubbs)]

Hi Leonard,

This branch looks good. Just one comment below.

merge-approved

-Edwin

>=== modified file 'src/launchpadlib/credentials.py'
>--- src/launchpadlib/credentials.py 2009-10-27 15:24:36 +0000
>+++ src/launchpadlib/credentials.py 2009-10-28 20:22:45 +0000
>+
>+ def get_http_credentials(self, cached_username=None, failed_attempts=0):

Missing docstring.

>+ username = self.input_username(
>+ cached_username, self.message(self.INPUT_USERNAME))
>+ if username is None:
>+ self.open_login_page_in_user_browser(
>+ urljoin(self.web_root, "+login"))
>+ raise NoLaunchpadAccount(
>+ self.message(self.YOU_NEED_A_LAUNCHPAD_ACCOUNT))
>+ password = self.input_password(self.message(self.INPUT_PASSWORD))
>+ response, content = self.browser.get_token_info(
>+ username, password, self.request_token, self.allow_access_levels)
>+ if response.status == 500:
>+ raise ServerError(self.message(SERVER_ERROR))
>+ elif response.status == 401:
>+ failed_attempts += 1
>+ if failed_attempts == self.max_failed_attempts:
>+ raise TooManyAuthenticationFailures(
>+ self.message(self.TOO_MANY_AUTHENTICATION_FAILURES))
>+ else:
>+ self.authentication_failure(
>+ self.message(self.AUTHENTICATION_FAILURE))
>+ return self.get_http_credentials(username, failed_attempts)
>+ token_info = simplejson.loads(content)
>+ return username, password, token_info

review: Approve (code)

=== added file 'src/launchpadlib/apps.py'
--- src/launchpadlib/apps.py	1970-01-01 00:00:00 +0000
+++ src/launchpadlib/apps.py	2009-10-28 20:20:23 +0000
@@ -0,0 +1,45 @@
+# Copyright 2009 Canonical Ltd.
+
+# This file is part of launchpadlib.
+#
+# launchpadlib is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Lesser General Public License as published by the
+# Free Software Foundation, version 3 of the License.
+#
+# launchpadlib is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+# for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with launchpadlib. If not, see <http://www.gnu.org/licenses/>.
+
+"""Command-line applications for Launchpadlib.
+
+This module contains the code for various applications. The applications
+themselves are kept in bin/.
+"""
+
+import simplejson
+
+from launchpadlib.credentials import Credentials
+from launchpadlib.uris import lookup_web_root
+
+
+class RequestTokenApp(object):
+    """An application that creates request tokens."""
+
+    def __init__(self, web_root, consumer_name, context):
+        """Initialize."""
+        self.web_root = lookup_web_root(web_root)
+        self.credentials = Credentials(consumer_name)
+        self.context = context
+
+    def run(self):
+        """Get a request token and return JSON information about it."""
+        token = self.credentials.get_request_token(
+            self.context, self.web_root,
+            token_format=Credentials.DICT_TOKEN_FORMAT)
+        return simplejson.dumps(token)
+
+

=== modified file 'src/launchpadlib/credentials.py'
--- src/launchpadlib/credentials.py	2009-10-27 15:24:36 +0000
+++ src/launchpadlib/credentials.py	2009-10-28 20:20:23 +0000
@@ -19,6 +19,7 @@
 __metaclass__ = type
 __all__ = [
     'AccessToken',
+    'AuthorizeRequestTokenProcess',
     'Consumer',
     'Credentials',
     ]
@@ -238,3 +239,221 @@
         elif not 'Almost finished' in content:
             response.status = 500 # Internal Server Error
         return response, content
+
+
+class AuthorizeRequestTokenProcess(object):
+
+    UNAUTHORIZED_ACCESS_LEVEL = "UNAUTHORIZED"
+
+    # Suggested messages for clients to display in common situations.
+
+    AUTHENTICATION_FAILURE = "I can't log in with the credentials you gave me. Let's try again."
+
+    CHOOSE_ACCESS_LEVEL = """Now it's time for you to decide how much power to give "%(app)s" over your Launchpad account."""
+
+    CHOOSE_ACCESS_LEVEL_ONE = CHOOSE_ACCESS_LEVEL + """
+
+"%(app)s" says it needs the following level of access to your Launchpad account: "%(level)s". It can't work with any other level of access, so denying this level of access means prohibiting "%(app)s" from using your Launchpad account at all."""
+
+    CHOSE_OTHER_THAN_UNAUTHORIZED = """Okay, I'm telling Launchpad to grant "%(app)s" access to your account."""
+
+    CHOSE_UNAUTHORIZED = """Okay, I'm going to cancel the request that "%(app)s" made for access to your account. You can always set this up again later."""
+
+    CLIENT_ERROR = """Sorry, but Launchpad is behaving in a way this client doesn't understand. There might be a bug in the client, a bug in the server, or this client might just be out of date."""
+
+    CONSUMER_MISMATCH = """WARNING: The application you're using told me its name was "%(old_consumer)s", but it told Launchpad its name was "%(real_consumer)s". This is probably not a problem, but it's a little suspicious, so you might want to look into this before continuing. I'll refer to the application as "%(real_consumer)s" from this point on."""
+
+    INPUT_USERNAME = "What email address do you use on Launchpad?"
+
+    INPUT_PASSWORD = "What's your Launchpad password?"
+
+    REQUEST_TOKEN_ALREADY_AUTHORIZED = """It looks like you already approved this request to grant "%(app)s" access to your Launchpad account. You shouldn't need to do anything more."""
+
+    SERVER_ERROR = "There seems to be something wrong on the Launchpad server side, and I can't continue. Hopefully this is a temporary problem, but if it persists, it's probably because of a bug in Lauchpad."
+
+    STARTUP_MESSAGE = """An application identified as "%(app)s" wants to access Launchpad on your behalf. I'm the Launchpad credential client and I'm here to ask for your Launchpad username and password.
+
+I'll use your Launchpad password to give "%(app)s" limited access to your Launchpad account. I will not show your password to "%(app)s" itself."""
+
+    SUCCESS = """You're all done! You should now be able to use Launchpad integration features of "%(app)s." """
+
+    SUCCESS_UNAUTHORIZED = """You're all done! "%(app)s" still doesn't have access to your Launchpad account."""
+
+    TOO_MANY_AUTHENTICATION_FAILURES = """You've failed the password entry too many times. I'm going to exit back to "%(app)s." Try again once you've solved the problem with your Launchpad account."""
+
+    YOU_NEED_A_LAUNCHPAD_ACCOUNT = """OK, you'll need to get yourself a Launchpad account before you can integrate Launchpad into "%(app)s."
+
+I'm opening the Launchpad registration page in your web browser so you can create an account. Once you've created an account, you can try this again."""
+
+    def __init__(self, web_root, consumer_name, request_token,
+                 allow_access_levels=[], max_failed_attempts=3):
+        self.web_root = web_root
+        self.consumer_name = consumer_name
+        self.request_token = request_token
+        self.browser = SimulatedLaunchpadBrowser(self.web_root)
+        self.max_failed_attempts = max_failed_attempts
+        self.allow_access_levels = allow_access_levels
+
+    def __call__(self):
+
+        self.startup(self.message(self.STARTUP_MESSAGE))
+
+        # Have the end-user enter their Launchpad username and password.
+        # Make sure the credentials are valid, and get information
+        # about the request token as a side effect.
+        username, password, token_info = self.get_http_credentials()
+
+        # Update this object with fresh information about the request token.
+        self.token_info = token_info
+        self.allow_access_levels = token_info['access_levels']
+        self._check_consumer()
+
+        # Have the end-user choose an access level from the fresh list.
+        if len(self.allow_access_levels) == 2:
+            # There's only one choice: allow access at a certain level
+            # or don't allow access at all.
+            message = self.CHOOSE_ACCESS_LEVEL_ONE
+            level = [level['title'] for level in self.allow_access_levels
+                     if level['value'] != self.UNAUTHORIZED_ACCESS_LEVEL]
+            extra = {'level' : level[0]}
+        else:
+            message = self.CHOOSE_ACCESS_LEVEL
+            extra = None
+        access_level = self.input_access_level(
+            self.allow_access_levels, self.message(message, extra))
+
+        # Notify the program of the user's choice.
+        if access_level == self.UNAUTHORIZED_ACCESS_LEVEL:
+            self.user_chose_unauthorized(
+                    self.message(self.CHOSE_UNAUTHORIZED))
+        else:
+            self.user_chose_other_than_unauthorized(
+                access_level,
+                self.message(self.CHOSE_OTHER_THAN_UNAUTHORIZED))
+
+        # Try to grant the specified level of access to the request token.
+        response, content = self.browser.grant_access(
+            username, password, self.request_token, access_level)
+        if response.status == 409:
+            raise RequestTokenAlreadyAuthorized(
+                self.message(self.REQUEST_TOKEN_ALREADY_AUTHORIZED))
+        elif response.status == 400:
+            raise ClientError(self.message(self.CLIENT_ERROR))
+        elif response.status == 500:
+            raise ServerError(self.message(SERVER_ERROR))
+        if access_level == self.UNAUTHORIZED_ACCESS_LEVEL:
+            message = self.SUCCESS_UNAUTHORIZED
+        else:
+            message = self.SUCCESS
+        self.success(self.message(message))
+
+    def get_http_credentials(self, cached_username=None, failed_attempts=0):
+        username = self.input_username(
+            cached_username, self.message(self.INPUT_USERNAME))
+        if username is None:
+            self.open_login_page_in_user_browser(
+                urljoin(self.web_root, "+login"))
+            raise NoLaunchpadAccount(
+                self.message(self.YOU_NEED_A_LAUNCHPAD_ACCOUNT))
+        password = self.input_password(self.message(self.INPUT_PASSWORD))
+        response, content = self.browser.get_token_info(
+            username, password, self.request_token, self.allow_access_levels)
+        if response.status == 500:
+            raise ServerError(self.message(SERVER_ERROR))
+        elif response.status == 401:
+            failed_attempts += 1
+            if failed_attempts == self.max_failed_attempts:
+                raise TooManyAuthenticationFailures(
+                    self.message(self.TOO_MANY_AUTHENTICATION_FAILURES))
+            else:
+                self.authentication_failure(
+                    self.message(self.AUTHENTICATION_FAILURE))
+                return self.get_http_credentials(username, failed_attempts)
+        token_info = simplejson.loads(content)
+        return username, password, token_info
+
+    def _check_consumer(self):
+        """Sanity-check the server consumer against the client consumer."""
+        real_consumer = self.token_info['oauth_token_consumer']
+        if real_consumer != self.consumer_name:
+            message = self.message(
+                self.CONSUMER_MISMATCH, { 'old_consumer' : self.consumer_name,
+                                          'real_consumer' : real_consumer })
+            self.server_consumer_differs_from_client_consumer(
+                self.consumer_name, real_consumer, message)
+            self.consumer_name = real_consumer
+
+    def message(self, raw_message, extra_variables=None):
+        """Prepare a message by plugging in the app name."""
+        variables = { 'app' : self.consumer_name }
+        if extra_variables is not None:
+            variables.update(extra_variables)
+        return raw_message % variables
+
+    def open_login_page_in_user_browser(self, url):
+        """Open the Launchpad login page in the user's web browser."""
+        webbrowser.open(url)
+
+    # You should define these methods in your subclass.
+
+    def startup(self, suggested_message):
+        """Hook method called on startup."""
+
+    def input_username(self, cached_username, suggested_message):
+        """Collect the Launchpad username from the end-user.
+
+        :param cached_username: A username from a previous entry attempt,
+        to be presented as the default.
+        """
+        raise NotImplementedError()
+
+    def input_password(self, suggested_message):
+        """Collect the Launchpad password from the end-user."""
+        raise NotImplementedError()
+
+    def input_access_level(self, available_levels, suggested_message):
+        """Collect the desired level of access from the end-user."""
+        raise NotImplementedError()
+
+    def authentication_failure(self, suggested_message):
+        """The user entered invalid credentials."""
+
+    def user_chose_unauthorized(self):
+        """The user refused to authorize a request token."""
+
+    def user_chose_other_than_unauthorized(self, access_level):
+        """The user authorized a request token with some access level."""
+
+    def server_consumer_differs_from_client_consumer(
+        self, client_name, real_name, suggested_message):
+        """The client seems to be lying or mistaken about its name.
+
+        When requesting a request token, the client told Launchpad
+        that its consumer name was "foo". Now the client is telling the
+        end-user that its name is "bar". Something is fishy and at the very
+        least the end-user should be warned about this.
+        """
+        pass
+
+    def success(self, suggested_message):
+        """The token was successfully authorized."""
+        pass
+
+
+class TokenAuthorizationException(Exception):
+    pass
+
+class RequestTokenAlreadyAuthorized(TokenAuthorizationException):
+    pass
+
+class ClientError(TokenAuthorizationException):
+    pass
+
+class ServerError(TokenAuthorizationException):
+    pass
+
+class NoLaunchpadAccount(TokenAuthorizationException):
+    pass
+
+class TooManyAuthenticationFailures(TokenAuthorizationException):
+    pass

=== modified file 'src/launchpadlib/docs/browser.txt'
--- src/launchpadlib/docs/browser.txt	2009-10-27 15:24:36 +0000
+++ src/launchpadlib/docs/browser.txt	2009-10-28 20:20:23 +0000
@@ -51,7 +51,11 @@
     ...     username, password, request_token)
     >>> print response['content-type']
     application/json
-    >>> response['content-location'] == validate_url
+
+    # XXX leonardr 2009-10-28 bug=462773 These two URLs should be
+    # exactly the same, but the Content-Location is missing the
+    # lp.context.
+    >>> validate_url.startswith(response['content-location'])
     True
 
     >>> import simplejson

=== added file 'src/launchpadlib/docs/trusted-client.txt'
--- src/launchpadlib/docs/trusted-client.txt	1970-01-01 00:00:00 +0000
+++ src/launchpadlib/docs/trusted-client.txt	2009-10-28 20:20:23 +0000
@@ -0,0 +1,160 @@
+***********************
+Making a trusted client
+***********************
+
+To authorize a request token, the end-user must type in their
+Launchpad username and password. Obviously, typing your password into
+a random program is a bad idea. The best case is to use a program you
+already trust with your Launchpad password: your web browser.
+
+But if you're writing an application that can't open the end-user's
+web browser, or you just really want a token authorization client that
+has the same UI as the rest of your application, you should use one of
+the trusted clients packaged with launchpadlib, rather than writing
+your own client.
+
+All the trusted clients are based on the same core code and implement
+the same workflow. This test implements a scriptable trusted client
+and uses it to test the behavior of the standard workflow.
+
+    >>> from launchpadlib.testing.helpers import (
+    ...     ScriptableRequestTokenAuthorization)
+
+Here we see the normal workflow, in which the user inputs all the
+correct data to authorize a request token.
+
+    >>> auth = ScriptableRequestTokenAuthorization(
+    ...     "consumer", "[e-mail]", "zeca",
+    ...     "WRITE_PRIVATE",
+    ...     allow_access_levels = ["WRITE_PUBLIC", "WRITE_PRIVATE"])
+    >>> access_token = auth()
+    What email address do you use on Launchpad?
+    What's your Launchpad password?
+    Now it's time for you to decide how much power to give "consumer" ...
+    ['UNAUTHORIZED', 'WRITE_PUBLIC', 'WRITE_PRIVATE']
+    Okay, I'm telling Launchpad to grant "consumer" access to your account.
+    You're all done! You should now be able to use Launchpad ...
+
+Ordinarily, the third-party program will create a request token and
+pass it into the trusted client. The test class is a little unusual:
+it takes care of creating the request token and, after the end-user
+has authorized it, exchanges the request token for an access
+token. This way we can verify that the entire end-to-end process
+works.
+
+    >>> access_token.key is not None
+    True
+
+Denying access
+==============
+
+It's always possible for the end-user to deny access to the
+application. This will make it impossible to convert the request token
+into an access token.
+
+    >>> auth = ScriptableRequestTokenAuthorization(
+    ...     "consumer", "[e-mail]", "zeca", "UNAUTHORIZED")
+    >>> access_token = auth()
+    What email address do you use on Launchpad?
+    ...
+    Okay, I'm going to cancel the request that "consumer" made...
+    You're all done! "consumer" still doesn't have access...
+    >>> access_token is None
+    True
+
+Only one allowable access level
+===============================
+
+When the application being authenticated only allows one access level,
+the authorizer creates a special message for display to the end-user.
+
+    >>> auth = ScriptableRequestTokenAuthorization(
+    ...     "consumer", "[e-mail]", "zeca",
+    ...     "WRITE_PRIVATE", allow_access_levels=["WRITE_PRIVATE"])
+
+    >>> auth()
+    What email address do you use on Launchpad?
+    ...
+    "consumer" says it needs the following level of access to your Launchpad
+    account: "Change Anything". It can't work with any other level of access,
+    so denying this level of access means prohibiting "consumer" from
+    using your Launchpad account at all.
+    ...
+
+Error handling
+==============
+
+Things can go wrong in many ways, most of which we can test with our
+scriptable authorizer. Here's a utility method to run the
+authorization process with a badly-scripted authorizer and print the
+resulting exception.
+
+    >>> from launchpadlib.credentials import TokenAuthorizationException
+    >>> def print_error(auth):
+    ...     try:
+    ...         auth()
+    ...     except TokenAuthorizationException, e:
+    ...         print str(e)
+
+Authentication failures
+-----------------------
+
+If the user doesn't have a Launchpad account, or refuses to type in
+their email address, the authorizer will open their web browser to the
+login page, and raise an exception.
+
+    >>> auth = ScriptableRequestTokenAuthorization(
+    ...     "consumer", None, "zeca", "WRITE_PRIVATE")
+    >>> print_error(auth)
+    What email address do you use on Launchpad?
+    [If this were a real application, ... opened to http://launchpad.dev:8085/+login]
+    OK, you'll need to get yourself a Launchpad account before you can ...
+    <BLANKLINE>
+    I'm opening the Launchpad registration page in your web browser ...
+
+If the user enters the wrong username/password combination too many
+times, the authorizer will give up and raise an exception.
+
+    >>> auth = ScriptableRequestTokenAuthorization(
+    ...     "consumer", "[e-mail]", "baddpassword",
+    ...     "WRITE_PRIVATE")
+    >>> print_error(auth)
+    What email address do you use on Launchpad?
+    What's your Launchpad password?
+    I can't log in with the credentials you gave me. Let's try again.
+    What email address do you use on Launchpad?
+    Cached username: [e-mail]
+    What's your Launchpad password?
+    You've failed the password entry too many times...
+
+The max_failed_attempts argument controls how many attempts the user
+is given to enter their username and password.
+
+    >>> auth = ScriptableRequestTokenAuthorization(
+    ...     "consumer", "bad username", "zeca",
+    ...     "WRITE_PRIVATE", max_failed_attempts=1)
+    >>> print_error(auth)
+    What email address do you use on Launchpad?
+    What's your Launchpad password?
+    You've failed the password entry too many times...
+
+Client duplicity
+----------------
+
+If the third-party client gives one consumer name to Launchpad, and a
+different consumer name to the authorizer, the authorizer will detect
+this possible duplicity and print a warning.
+
+    >>> auth = ScriptableRequestTokenAuthorization(
+    ...     "consumer1", "[e-mail]", "zeca",
+    ...     "WRITE_PRIVATE")
+
+We'll simulate this by changing the authorizer's .consumer_name after
+it obtained a request token from Launchpad.
+
+    >>> auth.consumer_name = "consumer2"
+    >>> auth()
+    What email address do you use on Launchpad?
+    ...
+    WARNING: The application you're using told me its name was "consumer2", but it told Launchpad its name was "consumer1"...
+    ...

=== modified file 'src/launchpadlib/testing/helpers.py'
--- src/launchpadlib/testing/helpers.py	2009-10-27 12:00:13 +0000
+++ src/launchpadlib/testing/helpers.py	2009-10-28 20:20:23 +0000
@@ -29,6 +29,8 @@
 
 
 from launchpadlib.launchpad import Launchpad
+from launchpadlib.credentials import (
+    AuthorizeRequestTokenProcess, Credentials)
 
 
 class TestableLaunchpad(Launchpad):
@@ -61,3 +63,90 @@
 salgado_with_full_permissions = KnownTokens('salgado-change-anything', 'test')
 salgado_read_nonprivate = KnownTokens('salgado-read-nonprivate', 'secret')
 nopriv_read_nonprivate = KnownTokens('nopriv-read-nonprivate', 'mystery')
+
+
+class ScriptableRequestTokenAuthorization(AuthorizeRequestTokenProcess):
+    """A request token process that doesn't need any user input.
+
+    The AuthorizeRequestTokenProcess is supposed to be hooked up to a
+    user interface, but that makes it difficult to test. This subclass
+    is designed to be easy to test.
+    """
+
+    def __init__(self, consumer_name, username, password, choose_access_level,
+                 allow_access_levels=[], max_failed_attempts=2,
+                 web_root="http://launchpad.dev:8085/"):
+
+        # Get a request token.
+        self.credentials = Credentials(consumer_name)
+        self.credentials.get_request_token(web_root=web_root)
+
+        # Initialize the superclass with the new request token.
+        super(ScriptableRequestTokenAuthorization, self).__init__(
+            web_root, consumer_name, self.credentials._request_token.key,
+                allow_access_levels, max_failed_attempts)
+
+        self.username = username
+        self.password = password
+        self.choose_access_level = choose_access_level
+
+    def __call__(self):
+        super(ScriptableRequestTokenAuthorization, self).__call__()
+
+        # Now verify that it worked by exchanging the authorized
+        # request token for an access token.
+        if self.choose_access_level != self.UNAUTHORIZED_ACCESS_LEVEL:
+            self.credentials.exchange_request_token_for_access_token(
+                web_root=self.web_root)
+            return self.credentials.access_token
+        return None
+
+    def open_login_page_in_user_browser(self, url):
+        """Print a status message."""
+        print ("[If this were a real application, the end-user's web "
+               "browser would be opened to %s]" % url)
+
+    def setup(self, suggested_message):
+        print suggested_message
+
+    def input_username(self, cached_username, suggested_message):
+        """Collect the Launchpad username from the end-user."""
+        print suggested_message
+        if cached_username is not None:
+            print "Cached username: " + cached_username
+        return self.username
+
+    def input_password(self, suggested_message):
+        """Collect the Launchpad password from the end-user."""
+        print suggested_message
+        return self.password
+
+    def input_access_level(self, available_levels, suggested_message):
+        """Collect the desired level of access from the end-user."""
+        print suggested_message
+        print [level['value'] for level in available_levels]
+        return self.choose_access_level
+
+    def authentication_failure(self, suggested_message):
+        """The user entered invalid credentials."""
+        print suggested_message
+
+    def user_chose_unauthorized(self, suggested_message):
+        """The user refused to authorize a request token."""
+        print suggested_message
+
+    def user_chose_other_than_unauthorized(self, access_level,
+                                           suggested_message):
+        """The user authorized a request token with some access level."""
+        print suggested_message
+
+    def server_consumer_differs_from_client_consumer(
+        self, client_name, real_name, suggested_message):
+        """The client seems to be lying or mistaken about its name."""
+        print suggested_message
+
+    def success(self, suggested_message):
+        """The token was successfully authorized."""
+        print suggested_message
+
+