Merge pull request #1644 from matrix-org/rav/is_token_grammar

Spec grammars for IS things

api/identity/definitions/request_email_validation.yaml

@@ -20,7 +20,11 @@ example: {
 properties:
   client_secret:
     type: string
-    description: A unique string used to identify the validation attempt.
+    description: |
+      A unique string generated by the client, and used to identify the
+      validation attempt. It must be a string consisting of the characters
+      ``[0-9a-zA-Z.=_-]``. Its length must not exceed 255 characters and it
+      must not be empty.
     example: "monkeys_are_GREAT"
   email:
     type: string

api/identity/definitions/request_msisdn_validation.yaml

@@ -21,7 +21,11 @@ example: {
 properties:
   client_secret:
     type: string
-    description: A unique string used to identify the validation attempt.
+    description: |
+      A unique string generated by the client, and used to identify the
+      validation attempt. It must be a string consisting of the characters
+      ``[0-9a-zA-Z.=_-]``. Its length must not exceed 255 characters and it
+      must not be empty.
     example: "monkeys_are_GREAT"
   country:
     type: string

api/identity/definitions/sid.yaml

@@ -15,6 +15,10 @@ type: object
 properties:
   sid:
     type: string
-    description: The session ID.
+    description: |
+      The session ID. Session IDs are opaque strings generated by the identity
+      server. They must consist entirely of the characters
+      ``[0-9a-zA-Z.=_-]``. Their length must not exceed 255 characters and they
+      must not be empty.
     example: "123abc"
 required: ['sid']

api/identity/email_associations.yaml

@@ -81,6 +81,12 @@ paths:
         associate the email address with any Matrix user ID. Specifically,
         calls to ``/lookup`` will not show a binding.
 
+        The identity server is free to match the token case-insensitively, or
+        carry out other mapping operations such as unicode
+        normalisation. Whether to do so is an implementation detail for the
+        identity server. Clients must always pass on the token without
+        modification.
+
         Note: for backwards compatibility with previous drafts of this
         specification, the parameters may also be specified as
         ``application/x-form-www-urlencoded`` data.  However, this usage is

api/identity/phone_associations.yaml

@@ -83,6 +83,12 @@ paths:
         associate the phone number address with any Matrix user
         ID. Specifically, calls to ``/lookup`` will not show a binding.
 
+        The identity server is free to match the token case-insensitively, or
+        carry out other mapping operations such as unicode
+        normalisation. Whether to do so is an implementation detail for the
+        identity server. Clients must always pass on the token without
+        modification.
+
         Note: for backwards compatibility with previous drafts of this
         specification, the parameters may also be specified as
         ``application/x-form-www-urlencoded`` data. However, this usage is

api/identity/store_invite.yaml

@@ -84,10 +84,15 @@ paths:
             properties:
               token:
                 type: string
-                description: The generated token.
+                description: |
+                  The generated token. Must be a string consisting of the
+                  characters ``[0-9a-zA-Z.=_-]``. Its length must not exceed
+                  255 characters and it must not be empty.
               public_keys:
                 type: array
-                description: A list of [server's long-term public key, generated ephemeral public key].
+                description: |
+                  A list of [server's long-term public key, generated ephemeral
+                  public key].
                 items:
                   type: string
               display_name:

specification/identity_service_api.rst

@@ -217,11 +217,24 @@ 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.
 
-To start a session, the client makes a request to the appropriate ``/requestToken``
+To start a session, the client makes a request to the appropriate
-endpoint. The user then receives a validation token which should be provided
+``/requestToken`` endpoint. The identity server then sends a validation token
-to the client. The client then provides the token to the appropriate ``/submitToken``
+to the user, and the user provides the token to the client. The client then
-endpoint, completing the session. At this point, the client should ``/bind`` the
+provides the token to the appropriate ``/submitToken`` endpoint, completing the
-third party identifier or leave it for another entity to bind.
+session. At this point, the client should ``/bind`` the third party identifier
+or leave it for another entity to bind.
+
+Format of a validation token
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The format of the validation token is left up to the identity server: it
+should choose one appropriate to the 3PID type. (For example, it would be
+inappropriate to expect a user to copy a long passphrase including punctuation
+from an SMS message into a client.)
+
+Whatever format the identity server uses, the validation token must consist of
+at most 255 Unicode codepoints. Clients must pass the token through without
+modification.
 
 Email associations
 ~~~~~~~~~~~~~~~~~~