Merge remote-tracking branch 'origin/master' into cross-signing-spec

Author: uhoreg

api/client-server/admin.yaml

@@ -82,7 +82,7 @@ paths:
               devices:
                 type: object
                 description: |-
-                  Each key is an identitfier for one of the user's devices.
+                  Each key is an identifier for one of the user's devices.
                 additionalProperties:
                   type: object
                   title: DeviceInfo

api/client-server/create_room.yaml

@@ -38,20 +38,26 @@ paths:
         the new room, including checking power levels for each event. It MUST
         apply the events implied by the request in the following order:
 
-        0. A default ``m.room.power_levels`` event, giving the room creator
+        1. The ``m.room.create`` event itself. Must be the first event in the
+           room.
+
+        2. An ``m.room.member`` event for the creator to join the room. This is
+           needed so the remaining events can be sent.
+
+        3. A default ``m.room.power_levels`` event, giving the room creator
            (and not other members) permission to send state events. Overridden
            by the ``power_level_content_override`` parameter.
 
-        1. Events set by the ``preset``. Currently these are the ``m.room.join_rules``,
+        4. Events set by the ``preset``. Currently these are the ``m.room.join_rules``,
            ``m.room.history_visibility``, and ``m.room.guest_access`` state events.
 
-        2. Events listed in ``initial_state``, in the order that they are
+        5. Events listed in ``initial_state``, in the order that they are
            listed.
 
-        3. Events implied by ``name`` and ``topic`` (``m.room.name`` and ``m.room.topic``
+        6. Events implied by ``name`` and ``topic`` (``m.room.name`` and ``m.room.topic``
            state events).
 
-        4. Invite events implied by ``invite`` and ``invite_3pid`` (``m.room.member`` with
+        7. Invite events implied by ``invite`` and ``invite_3pid`` (``m.room.member`` with
            ``membership: invite`` and ``m.room.third_party_invite``).
 
         The available presets do the following with respect to room state:

api/client-server/definitions/device_keys.yaml

@@ -47,6 +47,7 @@ properties:
       "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
   signatures:
     type: object
+    title: Signatures
     description: |-
        Signatures for the device key object. A map from user ID, to a map from
        ``<algorithm>:<device_id>`` to the signature.

api/client-server/definitions/third_party_signed.yaml

@@ -33,6 +33,10 @@ properties:
     type: object
     description: A signatures object containing a signature of the entire signed object.
     title: Signatures
+    additionalProperties:
+      type: object
+      additionalProperties:
+        type: string
     example: {
       "example.org": {
         "ed25519:0": "some9signature"

api/client-server/directory.yaml

@@ -19,15 +19,15 @@ host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%/directory
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
   - application/json
 securityDefinitions:
   $ref: definitions/security.yaml
 paths:
-  "/room/{roomAlias}":
+  "/directory/room/{roomAlias}":
     put:
       summary: Create a new mapping from room alias to room ID.
       operationId: setRoomAlias
@@ -129,7 +129,16 @@ paths:
       description: |-
         Remove a mapping of room alias to room ID.
 
-        Servers may choose to implement additional access control checks here, for instance that room aliases can only be deleted by their creator or a server administrator.
+        Servers may choose to implement additional access control checks here, for instance that
+        room aliases can only be deleted by their creator or a server administrator.
+
+        .. Note::
+           Servers may choose to update the ``alt_aliases`` for the ``m.room.canonical_alias``
+           state event in the room when an alias is removed. Servers which choose to update the
+           canonical alias event are recommended to, in addition to their other relevant permission
+           checks, delete the alias and return a successful response even if the user does not
+           have permission to update the ``m.room.canonical_alias`` event.
+
       operationId: deleteRoomAlias
       security:
         - accessToken: []
@@ -159,3 +168,70 @@ paths:
             "$ref": "definitions/errors/error.yaml"
       tags:
         - Room directory
+  "/rooms/{roomId}/aliases":
+    get:
+      summary: Get a list of local aliases on a given room.
+      description: |-
+        Get a list of aliases maintained by the local server for the
+        given room.
+
+        This endpoint can be called by users who are in the room (external
+        users receive an ``M_FORBIDDEN`` error response). If the room's
+        ``m.room.history_visibility`` maps to ``world_readable``, any
+        user can call this endpoint.
+
+        Servers may choose to implement additional access control checks here,
+        such as allowing server administrators to view aliases regardless of
+        membership.
+
+        .. Note::
+           Clients are recommended not to display this list of aliases prominently
+           as they are not curated, unlike those listed in the ``m.room.canonical_alias``
+           state event.
+
+      operationId: getLocalAliases
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room ID to find local aliases of.
+          required: true
+          x-example: "!abc123:example.org"
+      responses:
+        200:
+          description: |-
+            The list of local aliases for the room.
+          examples:
+            application/json: {
+              "aliases": [
+                "#somewhere:example.com",
+                "#another:example.com",
+                "#hat_trick:example.com"
+              ]
+            }
+          schema:
+            type: object
+            properties:
+              aliases:
+                type: array
+                description: The server's local aliases on the room. Can be empty.
+                items:
+                  type: string
+            required: ['aliases']
+        403:
+          description: The user is not permitted to retrieve the list of local aliases for the room.
+          examples:
+            application/json: {
+              "errcode": "M_FORBIDDEN",
+              "error": "You are not a member of the room."
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/errors/rate_limited.yaml"
+      tags:
+        - Room directory

api/client-server/keys.yaml

@@ -102,7 +102,7 @@ paths:
       responses:
         200:
           description:
-            The provided keys were sucessfully uploaded.
+            The provided keys were successfully uploaded.
           schema:
             type: object
             properties:

api/client-server/registration.yaml

@@ -328,8 +328,8 @@ paths:
 
         The homeserver may change the flows available depending on whether a
         valid access token is provided. The homeserver SHOULD NOT revoke the
-        access token provided in the request, however all other access tokens
-        for the user should be revoked if the request succeeds.
+        access token provided in the request. Whether other access tokens for
+        the user are revoked depends on the request parameters.
       security:
         - accessToken: []
       operationId: changePassword
@@ -343,6 +343,15 @@ paths:
                 type: string
                 description: The new password for the account.
                 example: "ihatebananas"
+              logout_devices:
+                type: boolean
+                description: |-
+                  Whether the user's other access tokens, and their associated devices, should be
+                  revoked if the request succeeds. Defaults to true.
+
+                  When ``false``, the server can still take advantage of `the soft logout method <#soft-logout>`_
+                  for the user's remaining devices.
+                example: true
               auth:
                 description: |-
                   Additional authentication information for the user-interactive authentication API.

api/client-server/room_send.yaml

@@ -85,5 +85,7 @@ paths:
                 type: string
                 description: |-
                   A unique identifier for the event.
+            required:
+              - event_id
       tags:
         - Room participation

api/client-server/room_state.yaml

@@ -45,6 +45,12 @@ paths:
         The body of the request should be the content object of the event; the
         fields in this object will vary depending on the type of event. See
         `Room Events`_ for the ``m.`` event specification.
+
+        If the event type being sent is ``m.room.canonical_alias`` servers
+        SHOULD ensure that any new aliases being listed in the event are valid
+        per their grammar/syntax and that they point to the room ID where the
+        state event is to be sent. Servers do not validate aliases which are
+        being removed or are already present in the state event.
       operationId: setRoomStateWithKey
       security:
         - accessToken: []
@@ -92,6 +98,8 @@ paths:
                 type: string
                 description: |-
                   A unique identifier for the event.
+            required:
+              - event_id
         403:
           description: |-
             The sender doesn't have permission to send the event into the room.
@@ -102,5 +110,23 @@ paths:
               "errcode": "M_FORBIDDEN",
               "error": "You do not have permission to send the event."
             }
+        400:
+          description: |-
+            The sender's request is malformed.
+
+            Some example error codes include:
+
+            * ``M_INVALID_PARAMETER``: One or more aliases within the ``m.room.canonical_alias``
+              event have invalid syntax.
+
+            * ``M_BAD_ALIAS``: One or more aliases within the ``m.room.canonical_alias`` event
+              do not point to the room ID for which the state event is to be sent to.
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_BAD_ALIAS",
+              "error": "The alias '#hello:example.org' does not point to this room."
+            }
       tags:
         - Room participation

api/openapi_extensions.md

@@ -43,3 +43,11 @@ doesn't work, as in the following example:
           properties:
             ...
 ```
+
+## OpenAPI 3's "2xx" format for response codes
+
+<!-- TODO: Remove this section after upgrading to OpenAPI v3 -->
+
+In some cases, the schema will have HTTP response code definitions like
+`2xx`, `3xx`, and `4xx`. These indicate that a response code within those
+ranges (`2xx` = `200` to `299`) is valid for the schema.