Merge pull request #88 from stygianguest/patch-1

docs/threepids/session/session.md

@@ -17,49 +17,63 @@
     - [Sessions disabled](#sessions-disabled)
 
 ## Overview
-When adding an email, a phone number or any other kind of 3PID (Third-Party Identifier) in a Matrix client, 
-the identity server is called to validate the 3PID.
+When adding an email, a phone number or any other kind of 3PID (Third-Party Identifier) in a Matrix client,
+the identity server is contacted to validate the 3PID.
+
+To validate the 3PID the identity server sends a message to the 3PID (e.g. an
+email) with a hyperlink back to a web-page managed by the identity server to
+confirm ownership of the 3PID.
 
 Once this 3PID is validated, the Homeserver will publish the user Matrix ID on the Identity Server and
 add this 3PID to the Matrix account which initiated the request.
 
-## Purpose
 This serves two purposes:
 - Add the 3PID as an administrative/# info for the Homeserver directly
 - Publish, or *Bind*, the 3PID so it can be queried from Homeservers and clients when inviting someone in a room
 by a 3PID, allowing it to be resolved to a Matrix ID.
 
 ## Federation
-Federation is based on the principle that one can get a domain name and serve services and information within that
-domain namespace in a way which can be discovered following a specific protocol or specification.
+In a federated set up, identity servers must cooperate to find the Matrix ID associated with a 3PID.
+
+Federation is based on the principle that each server is responsible for its own (dns) domain.
+Therefore only those 3PID can be federated that can be distinguished by their
+domain such as email addresses.
+
+Example: a user from Homeserver `example.org` adds an email `john@example.com`.  
+Federated identity servers would try to find the identity server at `example.com` and ask it for the Matrix ID of associated with `john@example.com`.
 
-In the Matrix eco-system, some 3PID can be federated (e.g. emails) while some others cannot (phone numbers).
-Also, Matrix users might add 3PIDs that would not point to the Identity server that actually holds the 3PID binding.  
+Nevertheless, Matrix users might add 3PIDs that are not associated to a domain, for example telephone numbers.
+Or they might even add 3PIDs associated to a different domain (such as an email address hosted by gmail).
+Such 3PIDs cannot be resolved in a federated way.
 
 Example: a user from Homeserver `example.org` adds an email `john@gmail.com`.  
 If a federated lookup was performed, Identity servers would try to find the 3PID bind at the `gmail.com` server, and
 not `example.org`.
 
-To allow global publishing of 3PID bindings to be found anywhere within the current protocol specification, one would
-perform a *Remote session* and *Remote bind*, effectively starting a new 3PID session with another Identity server on
-behalf of the user.  
+In order to resolve such 3PIDs, i.e. 3PIDs that cannot be resolved in a Federated way, an identity server can be configured such that
+- 3PIDs that cannot be resolved locally or using federation, are fowarded to another global identity server.
+- registration of new 3PIDs that cannot be looked up in a federated fashion, is forwarded to another global identity server.
+
+By forwarding a 3PIDs registration the identity creates a *Remote session* and *Remote bind*, effectively starting a new 3PID session with another Identity server on
+behalf of the user. 
+
 To ensure lookup works consistency within the current Matrix network, the central Matrix.org Identity Server should be
 used to store *remote* sessions and binds.
 
-On the flip side, at the time of writing, the Matrix specification and the central Matrix.org servers do not allow to
-remote a 3PID bind. This means that once a 3PID is published (email, phone number, etc.), it cannot be easily removed
-and would require contacting the Matrix.org administrators for each bind individually.  
+However, at the time of writing, the Matrix specification and the central Matrix.org servers do not allow to remote a 3PID bind.
+This means that once a 3PID is published (email, phone number, etc.), it cannot be easily removed
+and would require contacting the Matrix.org administrators for each bind individually.
 This poses a privacy, control and security concern, especially for groups/corporations that want to keep a tight control
 on where such identifiers can be made publicly visible.
 
-To ensure full control, validation management rely on two concepts:
+To ensure full control, validation management relies on two concepts:
 - The scope of 3PID being validated
 - The scope of 3PID sessions that should be possible/offered
 
 ### 3PID scope
 3PID can either be scoped as local or remote.
 
-Local means that they can looked up using federation and that such federation call would end up on the local
+Local means that they can be looked up using federation and that such a federation call would end up on the local
 Identity Server.  
 Remote means that they cannot be lookup using federation or that a federation call would not end up on the local
 Identity Server.
@@ -139,7 +153,7 @@ session.policy.validation.forRemote:
 `session.policy.validation` is the core configuration to control what users configured to use your Identity server
 are allowed to do in terms of 3PID sessions.
 
-The policy is divided contains a global on/off switch for 3PID sessions using `.enabled`  
+The policy has a global on/off switch for 3PID sessions using `.enabled`  
 It is also divided into two sections: `forLocal` and `forRemote` which refers to the 3PID scopes.  
 
 Each scope is divided into three parts: