async-matrix 0.1.3 → 1.0.0

data/data/matrix-spec/api/client-server/keys.yaml

@@ -0,0 +1,482 @@
+# Copyright 2016 OpenMarket Ltd
+# Copyright 2018 New Vector Ltd
+# Copyright 2020 The Matrix.org Foundation C.I.C.
+#
+# 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.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server Client Config API
+  version: 1.0.0
+paths:
+  /keys/upload:
+    post:
+      summary: Upload end-to-end encryption keys.
+      description: Publishes end-to-end encryption keys for the device.
+      operationId: uploadKeys
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                device_keys:
+                  description: |-
+                    Identity keys for the device. May be absent if no new
+                    identity keys are required.
+                  allOf:
+                    - $ref: definitions/device_keys.yaml
+                one_time_keys:
+                  allOf:
+                    - $ref: "definitions/one_time_keys.yaml"
+                  type: object
+                  description: |-
+                    One-time public keys for "pre-key" messages.  The names of
+                    the properties should be in the format
+                    `<algorithm>:<key_id>`. The format of the key is determined
+                    by the [key algorithm](/client-server-api/#key-algorithms).
+
+                    May be absent if no new one-time keys are required.
+                  example:
+                    signed_curve25519:AAAAHg:
+                      key: zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs
+                      signatures:
+                        "@alice:example.com":
+                          ed25519:JLAFKJWSCS: FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw
+                    signed_curve25519:AAAAHQ:
+                      key: j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw
+                      signatures:
+                        "@alice:example.com":
+                          ed25519:JLAFKJWSCS: IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA
+                fallback_keys:
+                  x-addedInMatrixVersion: "1.2"
+                  allOf:
+                    - $ref: "definitions/one_time_keys.yaml"
+                  type: object
+                  description: |-
+                    The public key which should be used if the device's one-time keys
+                    are exhausted. The fallback key is not deleted once used, but should
+                    be replaced when additional one-time keys are being uploaded. The
+                    server will notify the client of the fallback key being used through
+                    `/sync`.
+
+                    There can only be at most one key per algorithm uploaded, and the server
+                    will only persist one key per algorithm.
+
+                    When uploading a signed key, an additional `fallback: true` key should
+                    be included to denote that the key is a fallback key.
+
+                    May be absent if a new fallback key is not required.
+                  example:
+                    signed_curve25519:AAAAGj:
+                      key: zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs
+                      fallback: true
+                      signatures:
+                        "@alice:example.com":
+                          ed25519:JLAFKJWSCS: FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw
+        description: The keys to be published
+        required: true
+      responses:
+        "200":
+          description: The provided keys were successfully uploaded.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  one_time_key_counts:
+                    type: object
+                    additionalProperties:
+                      type: integer
+                    description: |-
+                      For each key algorithm, the number of unclaimed one-time keys
+                      of that type currently held on the server for this device.
+                      If an algorithm is not listed, the count for that algorithm
+                      is to be assumed zero.
+                    example:
+                      signed_curve25519: 20
+                required:
+                  - one_time_key_counts
+      tags:
+        - End-to-end encryption
+  /keys/query:
+    post:
+      summary: Download device identity keys.
+      description: Returns the current devices and identity keys for the given users.
+      operationId: queryKeys
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                timeout:
+                  type: integer
+                  description: |-
+                    The time (in milliseconds) to wait when downloading keys from
+                    remote servers. 10 seconds is the recommended default.
+                  example: 10000
+                device_keys:
+                  type: object
+                  description: |-
+                    The keys to be downloaded. A map from user ID, to a list of
+                    device IDs, or to an empty list to indicate all devices for the
+                    corresponding user.
+                  patternProperties:
+                    "^@":
+                      x-pattern-format: mx-user-id
+                      type: array
+                      items:
+                        type: string
+                        description: device ID
+                  example:
+                    "@alice:example.com": []
+              required:
+                - device_keys
+        description: Query defining the keys to be downloaded
+        required: true
+      responses:
+        "200":
+          description: The device information
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  failures:
+                    type: object
+                    description: |-
+                      If any remote homeservers could not be reached, they are
+                      recorded here. The names of the properties are the names of
+                      the unreachable servers.
+
+                      If the homeserver could be reached, but the user or device
+                      was unknown, no failure is recorded. Instead, the corresponding
+                      user or device is missing from the `device_keys` result.
+                    additionalProperties:
+                      type: object
+                    example: {}
+                  device_keys:
+                    type: object
+                    description: |-
+                      Information on the queried devices. A map from user ID, to a
+                      map from device ID to device information.  For each device,
+                      the information returned will be the same as uploaded via
+                      `/keys/upload`, with the addition of an `unsigned`
+                      property.
+                    patternProperties:
+                      "^@":
+                        x-pattern-format: mx-user-id
+                        type: object
+                        additionalProperties:
+                          title: DeviceInformation
+                          allOf:
+                            - $ref: definitions/device_keys.yaml
+                          properties:
+                            unsigned:
+                              title: UnsignedDeviceInfo
+                              type: object
+                              description: |-
+                                Additional data added to the device key information
+                                by intermediate servers, and not covered by the
+                                signatures.
+                              properties:
+                                device_display_name:
+                                  type: string
+                                  description: The display name which the user set on the device.
+                    example:
+                      "@alice:example.com":
+                        JLAFKJWSCS:
+                          user_id: "@alice:example.com"
+                          device_id: JLAFKJWSCS
+                          algorithms:
+                            - m.olm.v1.curve25519-aes-sha2
+                            - m.megolm.v1.aes-sha2
+                          keys:
+                            curve25519:JLAFKJWSCS: 3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI
+                            ed25519:JLAFKJWSCS: lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI
+                          signatures:
+                            "@alice:example.com":
+                              ed25519:JLAFKJWSCS: dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA
+                          unsigned:
+                            device_display_name: Alice's mobile phone
+                  master_keys:
+                    x-addedInMatrixVersion: "1.1"
+                    type: object
+                    description: |-
+                      Information on the master signing keys of the queried users.
+                      A map from user ID, to master signing key information.  For each key, the
+                      information returned will be the same as uploaded via
+                      `/keys/device_signing/upload`, along with the signatures
+                      uploaded via `/keys/signatures/upload` that the requesting user
+                      is allowed to see.
+                    patternProperties:
+                      "^@":
+                        x-pattern-format: mx-user-id
+                        allOf:
+                          - $ref: definitions/cross_signing_key.yaml
+                    example:
+                      "@alice:example.com":
+                        user_id: "@alice:example.com"
+                        usage:
+                          - master
+                        keys:
+                          ed25519:base64+master+public+key: base64+master+public+key
+                  self_signing_keys:
+                    x-addedInMatrixVersion: "1.1"
+                    type: object
+                    description: |-
+                      Information on the self-signing keys of the queried users. A map
+                      from user ID, to self-signing key information.  For each key, the
+                      information returned will be the same as uploaded via
+                      `/keys/device_signing/upload`.
+                    patternProperties:
+                      "^@":
+                        x-pattern-format: mx-user-id
+                        allOf:
+                          - $ref: definitions/cross_signing_key.yaml
+                    example:
+                      "@alice:example.com":
+                        user_id: "@alice:example.com"
+                        usage:
+                          - self_signing
+                        keys:
+                          ed25519:base64+self+signing+public+key: base64+self+signing+master+public+key
+                        signatures:
+                          "@alice:example.com":
+                            ed25519:base64+master+public+key: signature+of+self+signing+key
+                  user_signing_keys:
+                    type: object
+                    description: |-
+                      Information on the user-signing key of the user making the
+                      request, if they queried their own device information. A map
+                      from user ID, to user-signing key information.  The
+                      information returned will be the same as uploaded via
+                      `/keys/device_signing/upload`.
+                    patternProperties:
+                      "^@":
+                        x-pattern-format: mx-user-id
+                        allOf:
+                          - $ref: definitions/cross_signing_key.yaml
+                    example:
+                      "@alice:example.com":
+                        user_id: "@alice:example.com"
+                        usage:
+                          - user_signing
+                        keys:
+                          ed25519:base64+user+signing+public+key: base64+user+signing+master+public+key
+                        signatures:
+                          "@alice:example.com":
+                            ed25519:base64+master+public+key: signature+of+user+signing+key
+      tags:
+        - End-to-end encryption
+  /keys/claim:
+    post:
+      summary: Claim one-time encryption keys.
+      description: |-
+        Claims one-time keys for use in pre-key messages.
+
+        The request contains the user ID, device ID and algorithm name of the
+        keys that are required. If a key matching these requirements can be
+        found, the response contains it. The returned key is a one-time key
+        if one is available, and otherwise a fallback key.
+
+        One-time keys are given out in the order that they were uploaded via
+        [/keys/upload](/client-server-api/#post_matrixclientv3keysupload). (All
+        keys uploaded within a given call to `/keys/upload` are considered
+        equivalent in this regard; no ordering is specified within them.)
+
+        Servers must ensure that each one-time key is returned at most once,
+        so when a key has been returned, no other request will ever return
+        the same key.
+      operationId: claimKeys
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                timeout:
+                  type: integer
+                  description: |-
+                    The time (in milliseconds) to wait when downloading keys from
+                    remote servers. 10 seconds is the recommended default.
+                  example: 10000
+                one_time_keys:
+                  type: object
+                  description: |-
+                    The keys to be claimed. A map from user ID, to a map from
+                    device ID to algorithm name.
+                  patternProperties:
+                    "^@":
+                      x-pattern-format: mx-user-id
+                      type: object
+                      additionalProperties:
+                        type: string
+                        description: algorithm
+                        example: signed_curve25519
+                  example:
+                    "@alice:example.com":
+                      JLAFKJWSCS: signed_curve25519
+              required:
+                - one_time_keys
+        description: Query defining the keys to be claimed
+        required: true
+      responses:
+        "200":
+          description: The claimed keys.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  failures:
+                    type: object
+                    description: |-
+                      If any remote homeservers could not be reached, they are
+                      recorded here. The names of the properties are the names of
+                      the unreachable servers.
+
+                      If the homeserver could be reached, but the user or device
+                      was unknown, no failure is recorded. Instead, the corresponding
+                      user or device is missing from the `one_time_keys` result.
+                    additionalProperties:
+                      type: object
+                    example: {}
+                  one_time_keys:
+                    type: object
+                    description: |-
+                      One-time keys for the queried devices. A map from user ID, to a
+                      map from devices to a map from `<algorithm>:<key_id>` to the key object.
+
+                      See the [key algorithms](/client-server-api/#key-algorithms) section for information
+                      on the Key Object format.
+
+                      If necessary, the claimed key might be a fallback key. Fallback
+                      keys are re-used by the server until replaced by the device.
+                    patternProperties:
+                      "^@":
+                        x-pattern-format: mx-user-id
+                        type: object
+                        additionalProperties:
+                          $ref: "definitions/one_time_keys.yaml"
+                    example:
+                      "@alice:example.com":
+                        JLAFKJWSCS:
+                          signed_curve25519:AAAAHg:
+                            key: zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs
+                            signatures:
+                              "@alice:example.com":
+                                ed25519:JLAFKJWSCS: FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw
+                required:
+                  - one_time_keys
+      tags:
+        - End-to-end encryption
+  /keys/changes:
+    get:
+      summary: Query users with recent device key updates.
+      description: |-
+        Gets a list of users who have updated their device identity keys since a
+        previous sync token.
+
+        The server should include in the results any users who:
+
+        * currently share a room with the calling user (ie, both users have
+          membership state `join`); *and*
+        * added new device identity keys or removed an existing device with
+          identity keys, between `from` and `to`.
+      operationId: getKeysChanges
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: query
+          name: from
+          description: |-
+            The desired start point of the list. Should be the `next_batch` field
+            from a response to an earlier call to [`/sync`](/client-server-api/#get_matrixclientv3sync). Users who have not
+            uploaded new device identity keys since this point, nor deleted
+            existing devices with identity keys since then, will be excluded
+            from the results.
+          required: true
+          example: s72594_4483_1934
+          schema:
+            type: string
+        - in: query
+          name: to
+          description: |-
+            The desired end point of the list. Should be the `next_batch`
+            field from a recent call to [`/sync`](/client-server-api/#get_matrixclientv3sync) - typically the most recent
+            such call. This may be used by the server as a hint to check its
+            caches are up to date.
+          required: true
+          example: s75689_5632_2435
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The list of users who updated their devices.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  changed:
+                    type: array
+                    items:
+                      type: string
+                    description: |-
+                      The Matrix User IDs of all users who updated their device
+                      identity keys.
+                    example:
+                      - "@alice:example.com"
+                      - "@bob:example.org"
+                  left:
+                    type: array
+                    items:
+                      type: string
+                    description: |-
+                      The Matrix User IDs of all users who may have left all
+                      the end-to-end encrypted rooms they previously shared
+                      with the user.
+                    example:
+                      - "@clara:example.com"
+                      - "@doug:example.org"
+      tags:
+        - End-to-end encryption
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/data/matrix-spec/api/client-server/kicking.yaml

@@ -0,0 +1,110 @@
+# Copyright 2016 OpenMarket 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.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server Room Kicking API
+  version: 1.0.0
+paths:
+  "/rooms/{roomId}/kick":
+    post:
+      summary: Kick a user from the room.
+      description: |-
+        Kick a user from the room.
+
+        The caller must have the required power level in order to perform this operation.
+
+        Kicking a user adjusts the target member's membership state to be `leave` with an
+        optional `reason`. Like with other membership changes, a user can directly adjust
+        the target member's state by making a request to `/rooms/<room id>/state/m.room.member/<user id>`.
+      operationId: kick
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: roomId
+          description: The room identifier (not alias) from which the user should be kicked.
+          required: true
+          example: "!e42d8c:matrix.org"
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              example: {
+                "reason": "Telling unfunny jokes",
+                "user_id": "@cheeky_monkey:matrix.org"
+              }
+              properties:
+                user_id:
+                  type: string
+                  description: The fully qualified user ID of the user being kicked.
+                reason:
+                  type: string
+                  description: |-
+                    The reason the user has been kicked. This will be supplied as the
+                    `reason` on the target's updated [`m.room.member`](/client-server-api/#mroommember) event.
+              required:
+                - user_id
+        required: true
+      responses:
+        "200":
+          description: The user has been kicked from the room.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+        "403":
+          description: |-
+            You do not have permission to kick the user from the room. A meaningful `errcode` and
+            description error text will be returned. Example reasons for rejections are:
+
+            - The kicker is not currently in the room.
+            - The kickee is not currently in the room.
+            - The kicker's power level is insufficient to kick users from the room.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "You do not have a high enough power level to kick from this room."
+                  }
+      tags:
+        - Room membership
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer