Specify address validating and binding

specification/identity_service_api.rst

@@ -6,7 +6,8 @@ user identifiers. From time to time, it is useful to refer to users by other
 ("third-party") identifiers, or "3pid"s, e.g. their email address or phone
 number. This identity service specification describes how mappings between
 third-party identifiers and Matrix user identifiers can be established,
-verified, and used.
+validated, and used. This description technically may apply to any 3pid, but in
+practice has only been applied specifically to email addresses.
 
 .. contents:: Table of Contents
 .. sectnum::
@@ -14,7 +15,7 @@ verified, and used.
 General principles
 ------------------
 
-The purpose of an identity service is to verify, store, and answer questions
+The purpose of an identity service is to validate, store, and answer questions
 about the identities of users. In particular, it stores associations of the form
 "identifier X represents the same user as identifier Y", where identities may
 exist on different systems (such as email addresses, phone numbers,
@@ -22,11 +23,11 @@ Matrix user IDs, etc).
 
 The identity service has some private-public keypairs. When asked about an
 association, it will sign details of the association with its private key.
-Clients may verify the assertions about associations by verifying the signature
+Clients may validate the assertions about associations by verifying the signature
 with the public key of the identity service.
 
 In general, identity services are treated as reliable oracles. They do not
-necessarily provide evidence that they have verified associations, but claim to
+necessarily provide evidence that they have validated associations, but claim to
 have done so. Establishing the trustworthiness of an individual identity service
 is left as an exercise for the client.
 
@@ -64,6 +65,115 @@ Association Lookup
 
 {{lookup_is_http_api}}
 
+Establishing Associations
+-------------------------
+
+The flow for creating an association is session-based.
+
+Within a session, one may prove that one has ownership of a 3pid.
+Once this has been established, the user can form an association between that
+3pid and a Matrix user ID. Note that this association is only proved one way;
+a user can associate *any* Matrix user ID with a validated 3pid,
+i.e. I can claim that any email address I own is associated with
+@billg:microsoft.com.
+
+Sessions are time-limited; a session is considered to have been modified when
+it was created, and then when a validation is performed within it. A session can
+only be checked for validation, and validation can only be performed within a
+session, within a 24 hour period since its most recent modification. Any
+attempts to perform these actions after the expiry will be rejected, and a new
+session should be created and used instead.
+
+Creating a session
+~~~~~~~~~~~~~~~~~~
+
+A client makes a call to::
+
+ POST https://my.id.server:8090/_matrix/identity/v1/api/validate/email/requestToken
+
+ client_secret=monkeys_are_GREAT&
+ email=foo@bar.com&
+ send_attempt=1
+
+It may also optionally specify next_link. If next_link is specified, when the
+validation is completed, the identity service will redirect the user to that
+URL.
+
+This will create a new "session" on the identity service, identified by an
+``sid``.
+
+The identity service will send an email containing a token. If that token is
+presented to the identity service in the future, it indicates that that user was
+able to read the email for that email address, and so we validate ownership of
+the email address.
+
+We return the ``sid`` generated for this session to the caller, in a JSON object
+containing the ``sid`` key.
+
+If a send_attempt is specified, the server will only send an email if the
+send_attempt is a number greater than the most recent one which it has seen (or
+if it has never seen one), scoped to that email address + client_secret pair.
+This is to avoid repeatedly sending the same email in the case of request
+retries between the POSTing user and the identity service. The client should
+increment this value if they desire a new email (e.g. a reminder) to be sent.
+
+Validating ownership of an email
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A user may make either a ``GET`` or a ``POST`` request to
+``/_matrix/identity/v1/api/validate/email/submitToken`` with the following
+parameters (either as query parameters or URL-encoded POST parameters):
+- ``sid`` the sid for the session, generated by the ``requestToken`` call.
+- ``client_secret`` the client secret which was supplied to the ``requestToken`` call.
+- ``token`` the token generated by the ``requestToken`` call, and emailed to the user.
+
+If these three values are consistent with a set generated by a ``requestToken``
+call, ownership of the email address is considered to have been validated. This
+does not publish any information publicly, or associate the email address with
+any Matrix user ID. Specifically, calls to ``/lookup`` will not show a binding.
+
+Otherwise, an error will be returned.
+
+Checking non-published 3pid ownership
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A client can check whether ownership of a 3pid was validated by making an
+HTTP GET request to ``/_matrix/identity/v1/api/3pid/getValidated3pid``, passing
+the ``sid`` and ``client_secret`` as query parameters from the ``requestToken``
+call.
+
+It will return something of either the form::
+
+ {"medium": "email", "validated_at": 1457622739026, "address": "foo@bar.com"}
+
+or::
+
+ {"errcode": "M_SESSION_NOT_VALIDATED", "error": "This validation session has not yet been completed"}
+
+If the ``sid`` and ``client_secret`` were not recognised, or were not correct,
+an error will be returned.
+
+Publishing a validated association
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+An association between a session and a Matrix user ID can be published by making
+a URL-encoded HTTP POST request to ``/_matrix/identity/v1/api/3pid/bind`` with
+the following parameters::
+
+ sid=sid&
+ client_secret=monkeys_are_GREAT&
+ mxid=@foo:bar.com
+
+If the session is still valid, this will publish an association between the
+3pids validated on that session and the passed Matrix user ID. Future calls
+to ``/lookup`` for any of the session's 3pids will return this association.
+
+If the 3pid has not yet been validated, the HTTP request will be rejected, and
+the association will not be established.
+
+If the ``sid`` and ``client_secret`` were not recognised, or were not correct,
+an error will be returned.
+
 Invitation Storage
 ------------------