Merge pull request #1556 from turt2live/travis/is/cleanup

Identity Service API cleanup

api/identity/associations.yaml

@@ -46,10 +46,10 @@ paths:
           description: Validation information for the session.
           examples:
             application/json: {
-                "medium": "email",
+              "medium": "email",
-                "validated_at": 1457622739026,
+              "validated_at": 1457622739026,
-                "address": "louise@bobs.burgers"
+              "address": "louise@bobs.burgers"
-              }
+            }
           schema:
             type: object
             properties:
@@ -62,6 +62,7 @@ paths:
               validated_at:
                 type: integer
                 description: Timestamp indicating the time that the 3pid was validated.
+            required: ['medium', 'address', 'validated_at']
         400:
           description: |-
             The session has not been validated.
@@ -71,16 +72,20 @@ paths:
             ``errcode`` will be ``M_SESSION_EXPIRED``.
           examples:
             application/json: {
-                "errcode": "M_SESSION_NOT_VALIDATED",
+              "errcode": "M_SESSION_NOT_VALIDATED",
-                "error": "This validation session has not yet been completed"
+              "error": "This validation session has not yet been completed"
-              }
+            }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"
         404:
           description: The Session ID or client secret were not found
           examples:
             application/json: {
-                "errcode": "M_NO_VALID_SESSION",
+              "errcode": "M_NO_VALID_SESSION",
-                "error": "No valid session was found matching that sid and client secret"
+              "error": "No valid session was found matching that sid and client secret"
-              }
+            }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"
   "/bind":
     post:
       summary: Publish an association between a session and a Matrix user ID.
@@ -101,10 +106,10 @@ paths:
           schema:
             type: object
             example: {
-                "sid": "1234",
+              "sid": "1234",
-                "client_secret": "monkeys_are_GREAT",
+              "client_secret": "monkeys_are_GREAT",
-                "mxid": "@ears:matrix.org"
+              "mxid": "@ears:matrix.org"
-              }
+            }
             properties:
               sid:
                 type: string
@@ -121,19 +126,19 @@ paths:
           description: The association was published.
           examples:
             application/json: {
-                "address": "louise@bobs.burgers",
+              "address": "louise@bobs.burgers",
-                "medium": "email",
+              "medium": "email",
-                "mxid": "@ears:matrix.org",
+              "mxid": "@ears:matrix.org",
-                "not_before": 1428825849161,
+              "not_before": 1428825849161,
-                "not_after": 4582425849161,
+              "not_after": 4582425849161,
-                "ts": 1428825849161,
+              "ts": 1428825849161,
 
-                "signatures": {
+              "signatures": {
-                  "matrix.org": {
+                "matrix.org": {
-                    "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
+                  "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
-                  }
                 }
               }
+            }
           schema:
             type: object
             properties:
@@ -158,6 +163,15 @@ paths:
               signatures:
                 type: object
                 description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services.
+                $ref: "../../schemas/server-signatures.yaml"
+            required:
+              - address
+              - medium
+              - mxid
+              - not_before
+              - not_after
+              - ts
+              - signatures
         400:
           description: |-
             The association was not published.
@@ -167,13 +181,17 @@ paths:
             ``errcode`` will be ``M_SESSION_EXPIRED``.
           examples:
             application/json: {
-                "errcode": "M_SESSION_NOT_VALIDATED",
+              "errcode": "M_SESSION_NOT_VALIDATED",
-                "error": "This validation session has not yet been completed"
+              "error": "This validation session has not yet been completed"
-              }
+            }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"
         404:
           description: The Session ID or client secret were not found
           examples:
             application/json: {
-                "errcode": "M_NO_VALID_SESSION",
+              "errcode": "M_NO_VALID_SESSION",
-                "error": "No valid session was found matching that sid and client secret"
+              "error": "No valid session was found matching that sid and client secret"
-              }
+            }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"

api/identity/email_associations.yaml

@@ -51,10 +51,10 @@ paths:
           schema:
             type: object
             example: {
-                "client_secret": "monkeys_are_GREAT",
+              "client_secret": "monkeys_are_GREAT",
-                "email": "foo@example.com",
+              "email": "foo@example.com",
-                "send_attempt": 1
+              "send_attempt": 1
-              }
+            }
             properties:
               client_secret:
                 type: string
@@ -85,20 +85,28 @@ paths:
             Session created.
           examples:
             application/json: {
-                "sid": "1234"
+              "sid": "1234"
-              }
+            }
           schema:
             type: object
             properties:
               sid:
                 type: string
                 description: The session ID.
+            required: ['sid']
         400:
           description: |
             An error ocurred.  Some possible errors are:
 
             - ``M_INVALID_EMAIL``: The email address provided was invalid.
             - ``M_EMAIL_SEND_ERROR``: The validation email could not be sent.
+          examples:
+            application/json: {
+              "errcode": "M_INVALID_EMAIL",
+              "error": "The email address is not valid"
+            }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"
   "/validate/email/submitToken":
     post:
       summary: Validate ownership of an email address.
@@ -122,10 +130,10 @@ paths:
           schema:
             type: object
             example: {
-                "sid": "1234",
+              "sid": "1234",
-                "client_secret": "monkeys_are_GREAT",
+              "client_secret": "monkeys_are_GREAT",
-                "token": "atoken"
+              "token": "atoken"
-              }
+            }
             properties:
               sid:
                 type: string
@@ -143,14 +151,15 @@ paths:
             The success of the validation.
           examples:
             application/json: {
-                "success": true
+              "success": true
-              }
+            }
           schema:
             type: object
             properties:
               success:
                 type: boolean
                 description: Whether the validation was successful or not.
+            required: ['success']
     get:
       summary: Validate ownership of an email address.
       description: |-

api/identity/invitation_signing.yaml

@@ -68,9 +68,11 @@ paths:
               signatures:
                 type: object
                 description: The signature of the mxid, sender, and token.
+                $ref: "../../schemas/server-signatures.yaml"
               token:
                 type: string
                 description: The token for the invitation.
+            required: ['mxid', 'sender', 'signatures', 'token']
           examples:
             application/json: {
               "mxid": "@foo:bar.com",
@@ -84,7 +86,10 @@ paths:
             }
         404:
           description: Token was not found.
-          example: {
+          examples: 
+            application/json: {
               "errcode": "M_UNRECOGNIZED",
               "error": "Didn't recognize token"
             }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"

api/identity/lookup.yaml

@@ -49,19 +49,18 @@ paths:
             The association for that 3pid, or the empty object if no association is known.
           examples:
             application/json: {
-                "address": "louise@bobs.burgers",
+              "address": "louise@bobs.burgers",
-                "medium": "email",
+              "medium": "email",
-                "mxid": "@ears:matrix.org",
+              "mxid": "@ears:matrix.org",
-                "not_before": 1428825849161,
+              "not_before": 1428825849161,
-                "not_after": 4582425849161,
+              "not_after": 4582425849161,
-                "ts": 1428825849161,
+              "ts": 1428825849161,
-
+              "signatures": {
-                "signatures": {
+                "matrix.org": {
-                  "matrix.org": {
+                  "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
-                    "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
-                  }
                 }
               }
+            }
           schema:
             type: object
             properties:
@@ -86,6 +85,15 @@ paths:
               signatures:
                 type: object
                 description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services.
+                $ref: "../../schemas/server-signatures.yaml"
+            required:
+              - address
+              - medium
+              - mxid
+              - not_before
+              - not_after
+              - ts
+              - signatures
   "/bulk_lookup":
     post:
       summary: Lookup Matrix user IDs for a list of 3pids.
@@ -110,9 +118,11 @@ paths:
                 items:
                   type: array
                   title: 3PID mappings
+                  minItems: 2
+                  maxItems: 2
                   items:
-                    type: string
+                    - type: 3PID Medium
-                    title: 3PID medium or address
+                    - type: 3PID Address
                 description: an array of arrays containing the `3PID Types`_ with the ``medium`` in first position and the ``address`` in second position.
             required:
               - "threepids"
@@ -134,9 +144,12 @@ paths:
                 items:
                   type: array
                   title: 3PID mappings
+                  minItems: 3
+                  maxItems: 3
                   items:
-                    type: string
+                    - type: 3PID Medium
-                    title: 3PID medium or address or the Matrix ID
+                    - type: 3PID Address
+                    - type: Matrix User ID
                 description: an array of array containing the `3PID Types`_ with the ``medium`` in first position, the ``address`` in second position and Matrix ID in third position.
             required:
               - "threepids"

api/identity/phone_associations.yaml

@@ -51,11 +51,11 @@ paths:
           schema:
             type: object
             example: {
-                "client_secret": "monkeys_are_GREAT",
+              "client_secret": "monkeys_are_GREAT",
-                "country": "GB",
+              "country": "GB",
-                "phone_number": "07700900001",
+              "phone_number": "07700900001",
-                "send_attempt": 1
+              "send_attempt": 1
-              }
+            }
             properties:
               client_secret:
                 type: string
@@ -91,20 +91,28 @@ paths:
             Session created.
           examples:
             application/json: {
-                "sid": "1234"
+              "sid": "1234"
-              }
+            }
           schema:
             type: object
             properties:
               sid:
                 type: string
                 description: The session ID.
+            required: ['sid']
         400:
           description: |
             An error ocurred. Some possible errors are:
 
             - ``M_INVALID_ADDRESS``: The phone number provided was invalid.
             - ``M_SEND_ERROR``: The validation SMS could not be sent.
+          examples:
+            application/json: {
+              "errcode": "M_INVALID_ADDRESS",
+              "error": "The phone number is not valid"
+            }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"
   "/validate/msisdn/submitToken":
     post:
       summary: Validate ownership of a phone number.
@@ -128,10 +136,10 @@ paths:
           schema:
             type: object
             example: {
-                "sid": "1234",
+              "sid": "1234",
-                "client_secret": "monkeys_are_GREAT",
+              "client_secret": "monkeys_are_GREAT",
-                "token": "atoken"
+              "token": "atoken"
-              }
+            }
             properties:
               sid:
                 type: string
@@ -149,14 +157,15 @@ paths:
             The success of the validation.
           examples:
             application/json: {
-                "success": true
+              "success": true
-              }
+            }
           schema:
             type: object
             properties:
               success:
                 type: boolean
                 description: Whether the validation was successful or not.
+            required: ['success']
     get:
       summary: Validate ownership of a phone number.
       description: |-

api/identity/pubkey.yaml

@@ -45,13 +45,25 @@ paths:
             The public key exists.
           examples:
             application/json: {
-                "public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
+              "public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
-              }
+            }
           schema:
             type: object
             properties:
               public_key:
                 type: string
+                description: Unpadded Base64 encoded public key.
+            required: ['public_key']
+        404:
+          description:
+            The public key was not found.
+          examples:
+            application/json: {
+              "errcode": "M_NOT_FOUND",
+              "error": "The public key was not found"
+            }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"
   "/pubkey/isvalid":
     get:
       summary: Check whether a long-term public key is valid.
@@ -72,14 +84,15 @@ paths:
             The validity of the public key.
           examples:
             application/json: {
-                "valid": true
+              "valid": true
-              }
+            }
           schema:
             type: object
             properties:
               valid:
                 type: boolean
                 description: Whether the public key is recognised and is currently valid.
+            required: ['valid']
   "/pubkey/ephemeral/isvalid":
     get:
       summary: Check whether a short-term public key is valid.
@@ -108,3 +121,4 @@ paths:
               valid:
                 type: boolean
                 description: Whether the public key is recognised and is currently valid.
+            required: ['valid']

api/identity/store_invite.yaml

@@ -54,11 +54,11 @@ paths:
           schema:
             type: object
             example: {
-                "medium": "email",
+              "medium": "email",
-                "address": "foo@bar.baz",
+              "address": "foo@bar.baz",
-                "room_id": "!something:example.tld",
+              "room_id": "!something:example.tld",
-                "sender": "@bob:example.com"
+              "sender": "@bob:example.com"
-              }
+            }
             properties:
               medium:
                 type: string
@@ -90,15 +90,16 @@ paths:
               display_name:
                 type: string
                 description: The generated (redacted) display_name.
+            required: ['token', 'public_keys', 'display_name']
             example:
               application/json: {
-                  "token": "sometoken",
+                "token": "sometoken",
-                  "public_keys": [
+                "public_keys": [
-                    "serverpublickey",
+                  "serverpublickey",
-                    "ephemeralpublickey"
+                  "ephemeralpublickey"
-                  ],
+                ],
-                  "display_name": "f...@b..."
+                "display_name": "f...@b..."
-                }
+              }
         400:
           description: |
             An error has occured.
@@ -108,7 +109,9 @@ paths:
             error code will be ``M_UNRECOGNIZED``.
           examples:
             application/json: {
-                "errcode": "M_THREEPID_IN_USE",
+              "errcode": "M_THREEPID_IN_USE",
-                "error": "Binding already known",
+              "error": "Binding already known",
-                "mxid": mxid
+              "mxid": mxid
-              }
+            }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"

schemas/server-signatures.yaml

@@ -0,0 +1,24 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+type: object
+example: {
+  "example.com": {
+    "ed25519:0": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
+  }
+}
+additionalProperties:
+  type: object
+  title: Server Signatures
+  additionalProperties:
+    type: string

specification/identity_service_api.rst

@@ -23,7 +23,7 @@ user identifiers. From time to time, it is useful to refer to users by other
 number. This identity service specification describes how mappings between
 third-party identifiers and Matrix user identifiers can be established,
 validated, and used. This description technically may apply to any 3pid, but in
-practice has only been applied specifically to email addresses.
+practice has only been applied specifically to email addresses and phone numbers.
 
 .. contents:: Table of Contents
 .. sectnum::
@@ -56,6 +56,75 @@ is left as an exercise for the client.
 
 3PID types are described in `3PID Types`_ Appendix.
 
+API Standards
+-------------
+
+The mandatory baseline for identity service communication in Matrix is exchanging
+JSON objects over HTTP APIs. HTTPS is required for communication, and all API calls
+use a Content-Type of ``application/json``. In addition, strings MUST be encoded as
+UTF-8.
+
+Any errors which occur at the Matrix API level MUST return a "standard error response".
+This is a JSON object which looks like:
+
+.. code:: json
+
+  {
+    "errcode": "<error code>",
+    "error": "<error message>"
+  }
+
+The ``error`` string will be a human-readable error message, usually a sentence
+explaining what went wrong. The ``errcode`` string will be a unique string
+which can be used to handle an error message e.g. ``M_FORBIDDEN``. There may be
+additional keys depending on the error, but the keys ``error`` and ``errcode``
+MUST always be present.
+
+Some standard error codes are below:
+
+:``M_NOT_FOUND``:
+  The resource requested could not be located.
+
+:``M_MISSING_PARAMS``:
+  The request was missing one or more parameters.
+
+:``M_INVALID_PARAM``:
+  The request contained one or more invalid parameters.
+
+:``M_SESSION_NOT_VALIDATED``:
+  The session has not been validated.
+
+:``M_NO_VALID_SESSION``:
+  A session could not be located for the given parameters.
+
+:``M_SESSION_EXPIRED``:
+  The session has expired and must be renewed.
+
+:``M_INVALID_EMAIL``:
+  The email address provided was not valid.
+
+:``M_EMAIL_SEND_ERROR``:
+  There was an error sending an email. Typically seen when attempting to verify
+  ownership of a given email address.
+
+:``M_INVALID_ADDRESS``:
+  The provided third party address was not valid.
+
+:``M_SEND_ERROR``:
+  There was an error sending a notification. Typically seen when attempting to
+  verify ownership of a given third party address.
+
+:``M_UNRECOGNIZED``:
+  The request contained an unrecognised value, such as an unknown token or medium.
+
+:``M_THREEPID_IN_USE``:
+  The third party identifier is already in use by another user. Typically this
+  error will have an additional ``mxid`` property to indicate who owns the
+  third party identifier.
+
+:``M_UNKNOWN``:
+  An unknown error has occurred. 
+
 Privacy
 -------