Merge pull request #33 from portier/featSpec

First draft of the protocol specification, client-side

Specs.md

@@ -23,17 +23,18 @@ Some common terminology is used everywhere we try define the Portier protocol:
 - Identity Provider Discovery: The method with which the Identity Provider is
   discovered, based on the User email address.
 
-- Broker: A website that implements User authentication for the Relying Party,
-  optionally using Identity Provider Discovery and delagating to an Identity
-  Provider.
+- Broker: A website trusted by the Relying Party that implements User
+  authentication, optionally using Identity Provider Discovery and delegating
+  to an Identity Provider.
 
 ## Documents
 
-- [Email Normalization](specs/Email-Normalization.md), relevant to broker
-  implementors, and possibly relying parties that need to compare email
-  addresses.
+- [Email Normalization](specs/Email-Normalization.md), relevant to Broker
+  implementors, and possibly Relying Party implementors that need to compare
+  email addresses.
 
-- Relying Party Authentication Protocol (TODO)
+- [Portier Authentication Protocol](specs/Portier-Protocol.md), relevant to
+  Relying Party, Broker and Identity Provider implementors.
 
 - Identity Provider Discovery Protocol (TODO)
 

specs/Email-Normalization.md

@@ -5,7 +5,7 @@ implementation normalizes the email address as provided by the user. This
 document describes the normalization process.
 
 This document is relevant to the implementation of a broker. It may also be
-relevant to the implementation of a relying party (RP), when a verified email
+relevant to the implementation of a Relying Party (RP), when a verified email
 address (provided to the RP by its broker) needs to be compared with input
 obtained by other means.
 
@@ -63,6 +63,16 @@ Normalization takes a string _input_, and runs these steps:
  [IPv4 parsing]: https://url.spec.whatwg.org/#concept-ipv4-parser
  [forbidden host code point]: https://url.spec.whatwg.org/#forbidden-host-code-point
 
+## Normalized form
+
+In some validation steps of the Portier protocol, we mandate that an input
+email address is in 'normalized form'. Here 'normalized form' means the email
+address MUST conform to the output format of the normalization algorithm.
+
+In other words, when given an email address in normalized form as input,
+running the normalization algorithm on it MUST result in an output that doesn't
+change from / exactly matches the input.
+
 ## Normalization API
 
 A normalization API over HTTPS is defined here for use from runtime