--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README.md	Tue Jun 29 14:42:08 2010 -0700
@@ -0,0 +1,90 @@
+## The Mozilla Summit Identity Pal ##
+
+### Overview ###
+
+This project consists of two parts:
+
+  (1) A RESTful Web service that serves as a simple identity provider
+      and simple storage mechanism.
+
+  (2) A set of static HTML, JavaScript, and CSS files used as a
+      front-end for (1).
+
+Only individuals on an email whitelist can access the service at
+all. Each person has a 'bin' on the server which is only writable by
+them, but is readable by anyone else on the email whitelist.
+
+The authentication mechanism is as follows:
+
+  (1) Authentication is initiated by sending a POST request with an
+      email address to the service. Normally, this is performed by the
+      Web-based front-end.
+
+  (2) If the email address is on the whitelist, a URL with a challenge
+      token is sent to the address. The user is then expected to find
+      this email in their inbox and open this link in their browser, which
+      opens the web-based front-end. 
+
+  (3) At this point, the front-end sends the challenge token back to
+      the server, and an authorization token is returned. This token
+      is then permanently stored in the browser by the front-end, and
+      can be used at any time to issue a privileged request to the Web
+      service.
+
+By permanently storing the token in the browser, no password is
+needed; however, it should be noted that this means the browser should
+always be under the control of the same individual, i.e. not in a
+public place or shared by multiple family members. A separate browser
+profile, user-agent, or user account should be used in such cases.
+
+### Implementation And Dependencies ###
+
+The Web service is a Python-based wsgi app with no dependencies other
+than Python 2.6. This is encapsulated in the 'summitidp' package.
+
+Tests for the Web service are in the 'tests' directory, and require
+nose and webtest to run.
+
+The HTML5 front-end requires a modern, standard-compliant browser, and
+is actively tested on the latest production versions of Firefox,
+Safari, and Chrome with default profile settings. In particular, the
+front-end is not expected to work with browsers that have disabled DOM
+storage.
+
+Unfortunately, the front-end currently has no test suite.
+
+### Running The Test Suite ###
+
+Running the server's test suite can be accomplished by entering the
+project's root directory and running:
+
+  nosetests --with-doctest
+
+### Running The Development Server ###
+
+Before running the development server, the email whitelist needs to be
+created. To do this, create a new directory called 'storage' in the
+root directory of the project, and inside this create an
+attendees.json file with the following contents:
+
+  [
+    'bob@foo.com',
+    'jane@bar.com'
+  ]
+
+Obviously, the email addresses can be replaced with the actual ones on
+the whitelist if desired.
+
+A development server can be started by changing to the same directory and
+running:
+
+  python server.py
+
+Then, open this URL in a browser:
+
+  http://localhost:8000/
+
+This starts the HTML5 front-end. Instead of actually sending emails,
+however, the development server simply prints out a URL to stdout:
+this can be pasted into the browser to "validate" any user for
+development purposes.