Introducing F1 Authentication and Adding Site Content.

This change introduced the f1oauth and jesterpm oauth packages for
interacting with Fellowship One's developer API. I have also reworked
the login authentication to verify credentials through F1 and added
session management to track logged in users.

The Authenticator chain works as follows: on every page load we check
for a session cookie, if the cookie exists, the Request is marked as
authenticated and the OAuthUser object is restored in ClientInfo. If
this request is going to an account page, we require authentication. The
LoginFormAuthenticator checks if the user is already authenticated (via
cookie) and if not redirects the user to the login page. When the login
form is submitted, LoginFormAuthenticator catches the POST request and
authenticates the user through F1.

I'm also adding a new account page, but it is currently a work in
progress.

This commit also adds Allen's content to the site.

1 files changed, 143 insertions, 0 deletions

diff --git a/src/com/p4square/restlet/oauth/OAuthHelper.java b/src/com/p4square/restlet/oauth/OAuthHelper.java
new file mode 100644
index 0000000..544e4e3
--- /dev/null
+++ b/src/com/p4square/restlet/oauth/OAuthHelper.java
@@ -0,0 +1,143 @@
+/*
+ * Copyright 2013 Jesse Morgan
+ */
+
+package com.p4square.restlet.oauth;
+
+import java.net.URLEncoder;
+
+import org.restlet.Context;
+import org.restlet.Request;
+import org.restlet.Response;
+import org.restlet.Restlet;
+import org.restlet.data.ChallengeResponse;
+import org.restlet.data.ChallengeScheme;
+import org.restlet.data.Form;
+import org.restlet.data.Method;
+import org.restlet.data.Reference;
+import org.restlet.data.Status;
+import org.restlet.engine.Engine;
+
+/**
+ * Helper Class for OAuth 1.0 Authentication.
+ *
+ * @author Jesse Morgan <jesse@jesterpm.net>
+ */
+public abstract class OAuthHelper {
+    private final Restlet mDispatcher;
+    private final Token mConsumerToken;
+
+    /**
+     * Create a new OAuth Helper.
+     * As currently implemented, there can only be one OAuthHelper per Restlet
+     * Engine since this class registers its own provider for the OAuth
+     * authentication protocol.
+     *
+     * FIXME: This could be improved by making OAuthAuthenticationHelper and
+     * maybe Token aware of multiple service providers.
+     *
+     * @param context The restlet context which provides a ClientDispatcher.
+     * @param consumerKey The OAuth consumer key for this application.
+     * @param consumerSecret the OAuth consumer secret for this application.
+     */
+    public OAuthHelper(Context context, String consumerKey, String consumerSecret) {
+        mDispatcher = context.getClientDispatcher();
+        mConsumerToken = new Token(consumerKey, consumerSecret);
+
+        Engine.getInstance().getRegisteredAuthenticators().add(new OAuthAuthenticatorHelper(mConsumerToken));
+    }
+
+    /**
+     * @return the URL for the initial RequestToken request.
+     */
+    protected abstract String getRequestTokenUrl();
+
+    /**
+     * Request a RequestToken.
+     *
+     * @return a Token containing the RequestToken.
+     * @throws OAuthException if the request fails.
+     */
+    public Token getRequestToken() throws OAuthException {
+        Request request = new Request(Method.GET, getRequestTokenUrl());
+        request.setChallengeResponse(new ChallengeResponse(ChallengeScheme.HTTP_OAUTH));
+
+        Response response = mDispatcher.handle(request);
+
+        return processTokenRequest(response);
+    }
+
+    /**
+     * @return the URL to redirect the user to for Authentication.
+     */
+    public abstract String getLoginUrl(Token requestToken, String callback);
+
+    /**
+     * @return the URL for the AccessToken request.
+     */
+    protected abstract String getAccessTokenUrl();
+
+    /**
+     * Request an AccessToken for a previously authenticated RequestToken.
+     *
+     * @return an OAuthUser object containing the AccessToken.
+     * @throws OAuthException if the request fails.
+     */
+    public OAuthUser getAccessToken(Token requestToken) throws OAuthException {
+        Request request = new Request(Method.GET, getAccessTokenUrl());
+        request.setChallengeResponse(requestToken.getChallengeResponse());
+
+        return processAccessTokenRequest(request);
+    }
+
+    /**
+     * Helper method to decode the token returned from an OAuth Request.
+     *
+     * @param response The Response object from the Request.
+     * @return the Token from the oauth_token and oauth_token_secret parameters.
+     * @throws OAuthException is the server reported an error.
+     */
+    protected Token processTokenRequest(Response response) throws OAuthException {
+        Status status = response.getStatus();
+
+        if (status.isSuccess()) {
+            Form form = new Form(response.getEntity());
+            String token = form.getFirstValue("oauth_token");
+            String secret = form.getFirstValue("oauth_token_secret");
+
+            return new Token(token, secret);
+
+        } else {
+            throw new OAuthException(status);
+        }
+    }
+
+    /**
+     * Helper method to create an OAuthUser from the AccessToken request.
+     *
+     * The User's identifier is set to the Content-Location header, if present.
+     *
+     * @param response The Response to the AccessToken Request.
+     * @return An OAuthUser object wrapping the AccessToken.
+     * @throws OAuthException if the request failed.
+     */
+    protected OAuthUser processAccessTokenRequest(Request request) throws OAuthException {
+        Response response = getResponse(request);
+        Token accessToken = processTokenRequest(response);
+
+        Reference ref = response.getEntity().getLocationRef();
+        if (ref != null) {
+            return new OAuthUser(ref.toString(), accessToken);
+
+        } else {
+            return new OAuthUser(accessToken);
+        }
+    }
+
+    /**
+     * Helper method to get a Response for a Request.
+     */
+    protected Response getResponse(Request request) {
+        return mDispatcher.handle(request);
+    }
+}