Merge pull request #1615 from turt2live/travis/is/touchups

Touch up more of the identity service specification

api/identity/associations.yaml

@@ -18,15 +18,17 @@ info:
 host: localhost:8090
 schemes:
   - https
-  - http
 basePath: /_matrix/identity/api/v1
+consumes:
+  - application/json
 produces:
   - application/json
 paths:
   "/3pid/getValidated3pid":
     get:
       summary: Check whether ownership of a 3pid was validated.
-      description: A client can check whether ownership of a 3pid was validated
+      description: |-
+        Determines if a given 3pid has been validated by a user.
       operationId: getValidated3pid
       parameters:
         - in: query
@@ -61,7 +63,9 @@ paths:
                 description: The address of the 3pid being looked up.
               validated_at:
                 type: integer
-                description: Timestamp indicating the time that the 3pid was validated.
+                description: |-
+                  Timestamp, in milliseconds, indicating the time that the 3pid
+                  was validated.
             required: ['medium', 'address', 'validated_at']
         400:
           description: |-
@@ -78,7 +82,7 @@ paths:
           schema:
             $ref: "../client-server/definitions/errors/error.yaml"
         404:
-          description: The Session ID or client secret were not found
+          description: The Session ID or client secret were not found.
           examples:
             application/json: {
               "errcode": "M_NO_VALID_SESSION",
@@ -95,7 +99,7 @@ paths:
         Future calls to ``/lookup`` for any of the session\'s 3pids will return
         this association.
 
-        Note: for backwards compatibility with older versions of this
+        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
         deprecated.
@@ -132,7 +136,6 @@ paths:
               "not_before": 1428825849161,
               "not_after": 4582425849161,
               "ts": 1428825849161,
-
               "signatures": {
                 "matrix.org": {
                   "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
@@ -162,7 +165,10 @@ paths:
                 description: The unix timestamp at which the association was verified.
               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.
+                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

api/identity/email_associations.yaml

@@ -18,8 +18,9 @@ info:
 host: localhost:8090
 schemes:
   - https
-  - http
 basePath: /_matrix/identity/api/v1
+consumes:
+  - application/json
 produces:
   - application/json
 paths:
@@ -34,13 +35,13 @@ paths:
         that that user was able to read the email for that email address, and
         so we validate ownership of the email address.
 
-        Note that Home Servers offer APIs that proxy this API, adding
+        Note that homeservers offer APIs that proxy this API, adding
         additional behaviour on top, for example,
         ``/register/email/requestToken`` is designed specifically for use when
         registering an account and therefore will inform the user if the email
         address given is already registered on the server.
 
-        Note: for backwards compatibility with older versions of this
+        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
         deprecated.
@@ -58,7 +59,7 @@ paths:
             properties:
               client_secret:
                 type: string
-                description: A unique string used to identify the validation attempt
+                description: A unique string used to identify the validation attempt.
               email:
                 type: string
                 description: The email address to validate.
@@ -119,7 +120,7 @@ paths:
         associate the email address with any Matrix user ID. Specifically,
         calls to ``/lookup`` will not show a binding.
 
-        Note: for backwards compatibility with older versions of this
+        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
         deprecated.

api/identity/invitation_signing.yaml

@@ -18,8 +18,9 @@ info:
 host: localhost:8090
 schemes:
   - https
-  - http
 basePath: /_matrix/identity/api/v1
+consumes:
+  - application/json
 produces:
   - application/json
 paths:
@@ -29,7 +30,7 @@ paths:
       description: |-
         Sign invitation details.
 
-        The identity server will look up ``token`` which was stored in a call
+        The identity service will look up ``token`` which was stored in a call
         to ``store-invite``, and fetch the sender of the invite.
       operationId: blindlySignStuff
       parameters:
@@ -38,24 +39,24 @@ paths:
           schema:
             type: object
             example: {
-                "mxid": "@foo:bar.com",
+              "mxid": "@foo:bar.com",
-                "token": "sometoken",
+              "token": "sometoken",
-                "private_key": "base64encodedkey"
+              "private_key": "base64encodedkey"
-              }
+            }
             properties:
               mxid:
                 type: string
                 description: The Matrix user ID of the user accepting the invitation.
               token:
                 type: string
-                description: Token from the call to ``store-invite``
+                description: The token from the call to ``store-invite``.
               private_key:
                 type: string
                 description: The private key, encoded as `Unpadded base64`_.
             required: ["mxid", "token", "private_key"]
       responses:
         200:
-          description: The signedjson of the mxid, sender, and token.
+          description: The signed JSON of the mxid, sender, and token.
           schema:
             type: object
             properties:
@@ -85,7 +86,7 @@ paths:
               "token": "abc123"
             }
         404:
-          description: Token was not found.
+          description: The token was not found.
           examples: 
             application/json: {
               "errcode": "M_UNRECOGNIZED",

api/identity/lookup.yaml

@@ -1,6 +1,7 @@
 # Copyright 2016 OpenMarket Ltd
 # Copyright 2017 Kamax.io
 # Copyright 2017 New Vector Ltd
+# 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.
@@ -20,8 +21,9 @@ info:
 host: localhost:8090
 schemes:
   - https
-  - http
 basePath: /_matrix/identity/api/v1
+consumes:
+  - application/json
 produces:
   - application/json
 paths:
@@ -46,7 +48,7 @@ paths:
       responses:
         200:
           description:
-            The association for that 3pid, or the empty object if no association is known.
+            The association for that 3pid, or an empty object if no association is known.
           examples:
             application/json: {
               "address": "louise@bobs.burgers",
@@ -66,10 +68,10 @@ paths:
             properties:
               address:
                 type: string
-                description: The 3pid address of the user being looked up.
+                description: The 3pid address of the user being looked up, matching the address requested.
               medium:
                 type: string
-                description: The literal string "email".
+                description: A medium from the `3PID Types`_ Appendix, matching the medium requested.
               mxid:
                 type: string
                 description: The Matrix user ID associated with the 3pid.
@@ -126,7 +128,9 @@ paths:
                     #- type: 3PID Address
                     - type: string
                     - type: string
-                description: an array of arrays containing the `3PID Types`_ with the ``medium`` in first position and the ``address`` in second position.
+                description: |-
+                  An array of arrays containing the `3PID Types`_ with the ``medium``
+                  in first position and the ``address`` in second position.
             required:
               - "threepids"
       responses:
@@ -157,6 +161,9 @@ paths:
                     - type: string
                     - type: string
                     - type: string
-                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.
+                description: |-
+                  An array of array containing the `3PID Types`_ with the ``medium``
+                  in first position, the ``address`` in second position and Matrix user
+                  ID in third position.
             required:
               - "threepids"

api/identity/phone_associations.yaml

@@ -18,8 +18,9 @@ info:
 host: localhost:8090
 schemes:
   - https
-  - http
 basePath: /_matrix/identity/api/v1
+consumes:
+  - application/json
 produces:
   - application/json
 paths:
@@ -34,13 +35,13 @@ paths:
         indicates that that user was able to read the SMS for that phone
         number, and so we validate ownership of the phone number.
 
-        Note that Home Servers offer APIs that proxy this API, adding
+        Note that homeservers offer APIs that proxy this API, adding
         additional behaviour on top, for example,
         ``/register/msisdn/requestToken`` is designed specifically for use when
         registering an account and therefore will inform the user if the phone
         number given is already registered on the server.
 
-        Note: for backwards compatibility with older versions of this
+        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
         deprecated.
@@ -106,6 +107,8 @@ paths:
 
             - ``M_INVALID_ADDRESS``: The phone number provided was invalid.
             - ``M_SEND_ERROR``: The validation SMS could not be sent.
+            - ``M_DESTINATION_REJECTED``: The identity service cannot deliver an
+              SMS to the provided country or region.
           examples:
             application/json: {
               "errcode": "M_INVALID_ADDRESS",
@@ -125,7 +128,7 @@ paths:
         associate the phone number address with any Matrix user
         ID. Specifically, calls to ``/lookup`` will not show a binding.
 
-        Note: for backwards compatibility with older versions of this
+        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
         deprecated.

api/identity/ping.yaml

@@ -1,4 +1,5 @@
 # Copyright 2018 Kamax Sàrl
+# 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.
@@ -14,7 +15,7 @@
 
 swagger: "2.0"
 info:
-  title: "Matrix Client-Identity Versions API"
+  title: "Matrix Identity Service Ping API"
   version: "1.0.0"
 host: localhost:8090
 schemes:
@@ -25,19 +26,19 @@ produces:
 paths:
   "/api/v1":
     get:
-      summary: Checks that an Identity server is available at this API endpopint.
+      summary: Checks that an Identity Service is available at this API endpoint.
       description: |-
-        Checks that an Identity server is available at this API endpopint.
+        Checks that an Identity Service is available at this API endpoint.
 
-        To discover that an Identity server is available at a specific URL,
+        To discover that an Identity Service is available at a specific URL,
         this endpoint can be queried and will return an empty object.
 
         This is primarly used for auto-discovery and health check purposes
-        by entities acting as a client for the Identity server.
+        by entities acting as a client for the Identity Service.
       operationId: ping
       responses:
         200:
-          description: An Identity server is ready to serve requests.
+          description: An Identity Service is ready to serve requests.
           examples:
             application/json: {}
           schema:

api/identity/pubkey.yaml

@@ -18,8 +18,9 @@ info:
 host: localhost:8090
 schemes:
   - https
-  - http
 basePath: /_matrix/identity/api/v1
+consumes:
+  - application/json
 produces:
   - application/json
 paths:
@@ -113,8 +114,8 @@ paths:
             The validity of the public key.
           examples:
             application/json: {
-                "valid": true
+              "valid": true
-              }
+            }
           schema:
             type: object
             properties:

api/identity/store_invite.yaml

@@ -18,16 +18,17 @@ info:
 host: localhost:8090
 schemes:
   - https
-  - http
 basePath: /_matrix/identity/api/v1
+consumes:
+  - application/json
 produces:
   - application/json
 paths:
   "/store-invite":
     post:
-      summary: Store pending invitations to a user\'s 3pid.
+      summary: Store pending invitations to a user's 3pid.
       description: |-
-        Store pending invitations to a user\'s 3pid.
+        Store pending invitations to a user's 3pid.
 
         In addition to the request parameters specified below, an arbitrary
         number of other parameters may also be specified. These may be used in
@@ -47,6 +48,8 @@ paths:
 
         Also, the generated ephemeral public key will be listed as valid on
         requests to ``/_matrix/identity/api/v1/pubkey/ephemeral/isvalid``.
+
+        Currently, invites may only be issued for 3pids of the ``email`` medium.
       operationId: storeInvite
       parameters:
         - in: body
@@ -84,7 +87,7 @@ paths:
                 description: The generated token.
               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:
@@ -111,7 +114,7 @@ paths:
             application/json: {
               "errcode": "M_THREEPID_IN_USE",
               "error": "Binding already known",
-              "mxid": mxid
+              "mxid": "@alice:example.com"
             }
           schema:
             $ref: "../client-server/definitions/errors/error.yaml"

specification/identity_service_api.rst

@@ -1,6 +1,7 @@
 .. Copyright 2016 OpenMarket Ltd
 .. Copyright 2017 Kamax.io
 .. Copyright 2017 New Vector Ltd
+.. 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.
@@ -56,7 +57,7 @@ is left as an exercise for the client.
 
 3PID types are described in `3PID Types`_ Appendix.
 
-API Standards
+API standards
 -------------
 
 The mandatory baseline for identity service communication in Matrix is exchanging
@@ -136,6 +137,22 @@ should allow a 3pid to be mapped to a Matrix user identity, but not in the other
 direction (i.e. one should not be able to get all 3pids associated with a Matrix
 user ID, or get all 3pids associated with a 3pid).
 
+Web browser clients
+-------------------
+
+It is realistic to expect that some clients will be written to be run within a web
+browser or similar environment. In these cases, the identity service should respond to
+pre-flight requests and supply Cross-Origin Resource Sharing (CORS) headers on all
+requests.
+
+When a client approaches the server with a pre-flight (OPTIONS) request, the server
+should respond with the CORS headers for that route. The recommended CORS headers
+to be returned by servers on all requests are::
+
+  Access-Control-Allow-Origin: *
+  Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
+  Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization
+
 Status check
 ------------
 
@@ -146,25 +163,24 @@ Key management
 
 An identity service has some long-term public-private keypairs. These are named
 in a scheme ``algorithm:identifier``, e.g. ``ed25519:0``. When signing an
-association, the Matrix standard JSON signing format is used, as specified in
+association, the standard `Signing JSON`_ algorithm applies.
-the server-server API specification under the heading "Signing Events".
 
 In the event of key compromise, the identity service may revoke any of its keys.
 An HTTP API is offered to get public keys, and check whether a particular key is
 valid.
 
-The identity server may also keep track of some short-term public-private
+The identity service may also keep track of some short-term public-private
 keypairs, which may have different usage and lifetime characteristics than the
 service's long-term keys.
 
 {{pubkey_is_http_api}}
 
-Association Lookup
+Association lookup
 ------------------
 
 {{lookup_is_http_api}}
 
-Establishing Associations
+Establishing associations
 -------------------------
 
 The flow for creating an association is session-based.
@@ -183,6 +199,12 @@ 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``
+endpoint. The user then receives a validation token which should be provided
+to the client. The client then provides the token to the appropriate ``/submitToken``
+endpoint, completing the session. At this point, the client should ``/bind`` the
+third party identifier or leave it for another entity to bind.
+
 Email associations
 ~~~~~~~~~~~~~~~~~~
 
@@ -198,53 +220,31 @@ General
 
 {{associations_is_http_api}}
 
-Invitation Storage
+Invitation storage
 ------------------
 
 An identity service can store pending invitations to a user's 3pid, which will
 be retrieved and can be either notified on or look up when the 3pid is
 associated with a Matrix user ID.
 
-At a later point, if the owner of that particular 3pid binds it with a Matrix user ID, the identity server will attempt to make an HTTP POST to the Matrix user's homeserver which looks roughly as below::
+At a later point, if the owner of that particular 3pid binds it with a Matrix user
-
+ID, the identity service will attempt to make an HTTP POST to the Matrix user's
- POST https://bar.com:8448/_matrix/federation/v1/3pid/onbind
+homeserver via the `/3pid/onbind`_ endpoint. The request MUST be signed with a
- Content-Type: application/json
+long-term private key for the identity service.
-
- {
-  "medium": "email",
-  "address": "foo@bar.baz",
-  "mxid": "@alice:example.tld",
-  "invites": [
-    {
-      "medium": "email",
-      "address": "foo@bar.baz",
-      "mxid": "@alice:example.tld",
-      "room_id": "!something:example.tld",
-      "sender": "@bob:example.tld",
-      "signed": {
-        "mxid": "@alice:example.tld",
-        "signatures": {
-          "vector.im": {
-            "ed25519:0": "somesignature"
-          }
-        },
-        "token": "sometoken"
-      }
-    }
-  ]
- }
-
-Where the signature is produced using a long-term private key.
 
 {{store_invite_is_http_api}}
 
 Ephemeral invitation signing
 ----------------------------
 
-To aid clients who may not be able to perform crypto themselves, the identity service offers some crypto functionality to help in accepting invitations.
+To aid clients who may not be able to perform crypto themselves, the identity
-This is less secure than the client doing it itself, but may be useful where this isn't possible.
+service offers some crypto functionality to help in accepting invitations.
+This is less secure than the client doing it itself, but may be useful where
+this isn't possible.
 
 {{invitation_signing_is_http_api}}
 
 .. _`Unpadded Base64`:  ../appendices.html#unpadded-base64
 .. _`3PID Types`:  ../appendices.html#pid-types
+.. _`Signing JSON`: ../appendices.html#signing-json
+.. _`/3pid/onbind`: ../server_server.html#put-matrix-federation-v1-3pid-onbind