async-matrix 0.1.2 → 1.0.0

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

@@ -0,0 +1,306 @@
+# Copyright 2016 OpenMarket 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.
+# 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 Creation API
+  version: 1.0.0
+paths:
+  /createRoom:
+    post:
+      summary: Create a new room
+      description: |-
+        Create a new room with various configuration options.
+
+        The server MUST apply the normal state resolution rules when creating
+        the new room, including checking power levels for each event. It MUST
+        apply the events implied by the request in the following order:
+
+        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. Overridden by the
+           `power_level_content_override` parameter.
+
+           In [room versions](/rooms) 1 through 11, the room creator (and not
+           other members) will be given permission to send state events.
+
+           In room versions 12 and later, the room creator is given infinite
+           power level and cannot be specified in the `users` field of
+           `m.room.power_levels`, so is not listed explicitly.
+
+           **Note**: For `trusted_private_chat`, the users specified in the
+           `invite` parameter SHOULD also be appended to `additional_creators`
+           by the server, per the `creation_content` parameter.
+
+           If the room's version is 12 or higher, the power level for sending
+           `m.room.tombstone` events MUST explicitly be higher than `state_default`.
+           For example, set to 150 instead of 100.
+
+        4. An `m.room.canonical_alias` event if `room_alias_name` is given.
+
+        5. Events set by the `preset`. Currently these are the `m.room.join_rules`,
+           `m.room.history_visibility`, and `m.room.guest_access` state events.
+
+        6. Events listed in `initial_state`, in the order that they are
+           listed.
+
+        7. Events implied by `name` and `topic` (`m.room.name` and `m.room.topic`
+           state events).
+
+        8. 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:
+
+        | Preset                 | `join_rules` | `history_visibility` | `guest_access` | Other |
+        |------------------------|--------------|----------------------|----------------|-------|
+        | `private_chat`         | `invite`     | `shared`             | `can_join`     |       |
+        | `trusted_private_chat` | `invite`     | `shared`             | `can_join`     | All invitees are given the same power level as the room creator. |
+        | `public_chat`          | `public`     | `shared`             | `forbidden`    |       |
+
+        The server will create a `m.room.create` event in the room with the
+        requesting user as the creator, alongside other keys provided in the
+        `creation_content` or implied by behaviour of `creation_content`.
+      operationId: createRoom
+      x-changedInMatrixVersion:
+        "1.16": Added server behaviour for how the initial power levels change depending on room version.
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              example: {
+                "preset": "public_chat",
+                "room_alias_name": "thepub",
+                "name": "The Grand Duke Pub",
+                "topic": "All about happy hour",
+                "creation_content": {
+                  "m.federate": false
+                }
+              }
+              properties:
+                visibility:
+                  type: string
+                  enum:
+                    - public
+                    - private
+                  description: |-
+                    The room's visibility in the server's
+                    [published room directory](/client-server-api#published-room-directory).
+                    Defaults to `private`.
+                room_alias_name:
+                  type: string
+                  description: |-
+                    The desired room alias **local part**. If this is included, a
+                    room alias will be created and mapped to the newly created
+                    room. The alias will belong on the *same* homeserver which
+                    created the room. For example, if this was set to "foo" and
+                    sent to the homeserver "example.com" the complete room alias
+                    would be `#foo:example.com`.
+
+                    The complete room alias will become the canonical alias for
+                    the room and an `m.room.canonical_alias` event will be sent
+                    into the room.
+                name:
+                  type: string
+                  description: |-
+                    If this is included, an [`m.room.name`](/client-server-api/#mroomname) event
+                    will be sent into the room to indicate the name for the room.
+                    This overwrites any [`m.room.name`](/client-server-api/#mroomname)
+                    event in `initial_state`.
+                topic:
+                  type: string
+                  description: |-
+                    If this is included, an [`m.room.topic`](/client-server-api/#mroomtopic)
+                    event with a `text/plain` mimetype will be sent into the room
+                    to indicate the topic for the room. This overwrites any
+                    [`m.room.topic`](/client-server-api/#mroomtopic) event in `initial_state`.
+                invite:
+                  type: array
+                  description: |-
+                    A list of user IDs to invite to the room. This will tell the
+                    server to invite everyone in the list to the newly created room.
+                  items:
+                    type: string
+                invite_3pid:
+                  type: array
+                  description: |-
+                    A list of objects representing third-party IDs to invite into
+                    the room.
+                  items:
+                    $ref: definitions/invite_3pid.yaml
+                room_version:
+                  type: string
+                  description: |-
+                    The room version to set for the room. If not provided, the homeserver is
+                    to use its configured default. If provided, the homeserver will return a
+                    400 error with the errcode `M_UNSUPPORTED_ROOM_VERSION` if it does not
+                    support the room version.
+                  example: "1"
+                creation_content:
+                  title: CreationContent
+                  type: object
+                  x-changedInMatrixVersion:
+                    "1.16": Added server behaviour for how to handle `trusted_private_chat` and invited users.
+                  description: |-
+                    Extra keys, such as `m.federate`, to be added to the content
+                    of the [`m.room.create`](/client-server-api/#mroomcreate) event.
+
+                    The server will overwrite the following
+                    keys: `creator`, `room_version`. Future versions of the specification
+                    may allow the server to overwrite other keys.
+
+                    When using the `trusted_private_chat` preset, the server SHOULD combine
+                    `additional_creators` specified here and the `invite` array into the
+                    eventual `m.room.create` event's `additional_creators`, deduplicating
+                    between the two parameters.
+                initial_state:
+                  type: array
+                  description: |-
+                    A list of state events to set in the new room. This allows
+                    the user to override the default state events set in the new
+                    room. The expected format of the state events are an object
+                    with type, state_key and content keys set.
+
+                    Takes precedence over events set by `preset`, but gets
+                    overridden by `name` and `topic` keys.
+                  items:
+                    type: object
+                    title: StateEvent
+                    properties:
+                      type:
+                        type: string
+                        description: The type of event to send.
+                      state_key:
+                        type: string
+                        description: The state_key of the state event. Defaults to an empty string.
+                      content:
+                        type: object
+                        description: The content of the event.
+                    required:
+                      - type
+                      - content
+                preset:
+                  type: string
+                  enum:
+                    - private_chat
+                    - public_chat
+                    - trusted_private_chat
+                  description: |-
+                    Convenience parameter for setting various default state events
+                    based on a preset.
+
+                    If unspecified, the server should use the `visibility` to determine
+                    which preset to use. A visibility of `public` equates to a preset of
+                    `public_chat` and `private` visibility equates to a preset of
+                    `private_chat`.
+                is_direct:
+                  type: boolean
+                  description: |-
+                    This flag makes the server set the `is_direct` flag on the
+                    `m.room.member` events sent to the users in `invite` and
+                    `invite_3pid`. See [Direct Messaging](/client-server-api/#direct-messaging) for more information.
+                power_level_content_override:
+                  title: Power Level Event Content
+                  type: object
+                  description: |-
+                    The power level content to override in the default power level
+                    event. This object is applied on top of the generated
+                    [`m.room.power_levels`](/client-server-api/#mroompower_levels)
+                    event content prior to it being sent to the room. Defaults to
+                    overriding nothing.
+        description: The desired room configuration.
+        required: true
+      responses:
+        "200":
+          description: Information about the newly created room.
+          content:
+            application/json:
+              schema:
+                type: object
+                description: Information about the newly created room.
+                properties:
+                  room_id:
+                    type: string
+                    description: The created room's ID.
+                required:
+                  - room_id
+              examples:
+                response:
+                  value: {
+                    "room_id": "!sefiuhWgwghwWgh:example.com"
+                  }
+        "400":
+          description: |-
+            The request is invalid. A meaningful `errcode` and description
+            error text will be returned. Example reasons for rejection include:
+
+            - The request body is malformed (`errcode` set to `M_BAD_JSON`
+              or `M_NOT_JSON`).
+
+            - The room alias specified is already taken (`errcode` set to
+              `M_ROOM_IN_USE`).
+
+            - The initial state implied by the parameters to the request is
+              invalid: for example, the user's `power_level` is set below
+              that necessary to set the room name (`errcode` set to
+              `M_INVALID_ROOM_STATE`).
+
+            - The homeserver doesn't support the requested room version, or
+              one or more users being invited to the new room are residents
+              of a homeserver which does not support the requested room version.
+              The `errcode` will be `M_UNSUPPORTED_ROOM_VERSION` in these
+              cases.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+        "403":
+          description: |-
+            Creating the room is not allowed.
+
+            {{% added-in v="1.18"%}} The `M_INVITE_BLOCKED` error code is used to
+            indicate that one of the homeservers of the invited users rejected
+            the invite due to [invite blocking](/client-server-api/#invite-permission).
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+      tags:
+        - Room creation
+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/cross_signing.yaml

@@ -0,0 +1,300 @@
+# 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 Cross Signing API
+  version: 1.0.0
+paths:
+  /keys/device_signing/upload:
+    post:
+      x-addedInMatrixVersion: "1.1"
+      x-changedInMatrixVersion:
+        "1.11": UIA is not always required for this endpoint.
+        "1.17": |-
+          This endpoint no longer requires User-Interactive Authentication when used by an
+          application service.
+      summary: Upload cross-signing keys.
+      description: |-
+        Publishes cross-signing keys for the user.
+
+        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api),
+        except when used by an application service.
+
+        User-Interactive Authentication MUST be performed for regular clients, except in these cases:
+        - there is no existing master signing key uploaded to the homeserver, OR
+        - there is an existing master signing key and it exactly matches the
+          master signing key provided in the request body. If there are any additional
+          keys provided in the request (self-signing key, user-signing key) they MUST also
+          match the existing keys stored on the server. In other words, the request contains
+          no new keys.
+
+        This allows clients to freely upload one set of keys, but not modify/overwrite keys if
+        they already exist. Allowing clients to upload the same set of keys more than once
+        makes this endpoint idempotent in the case where the response is lost over the network,
+        which would otherwise cause a UIA challenge upon retry.
+
+        {{% boxes/note %}}
+        When this endpoint requires User-Interactive Authentication,
+        it uses the [`m.oauth`](/client-server-api/#oauth-authentication)
+        authentication type if the access token was obtained
+        via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        {{% /boxes/note %}}
+      operationId: uploadCrossSigningKeys
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                master_key:
+                  description: Optional. The user\'s master signing key.
+                  allOf:
+                    - $ref: definitions/cross_signing_key.yaml
+                self_signing_key:
+                  description: |-
+                    Optional. The user\'s self-signing key. Must be signed by
+                    the accompanying master signing key, or by the user\'s most recently
+                    uploaded master signing key if no master signing key is included in the
+                    request.
+                  allOf:
+                    - $ref: definitions/cross_signing_key.yaml
+                user_signing_key:
+                  description: |-
+                    Optional. The user\'s user-signing key. Must be signed by
+                    the accompanying master signing key, or by the user\'s most recently
+                    uploaded master signing key if no master signing key is included in the
+                    request.
+                  allOf:
+                    - $ref: definitions/cross_signing_key.yaml
+                auth:
+                  description: |-
+                    Additional authentication information for the
+                    user-interactive authentication API.
+                  allOf:
+                    - $ref: definitions/auth_data.yaml
+              example: {
+                "auth": {
+                  "type": "example.type.foo",
+                  "session": "xxxxx",
+                  "example_credential": "verypoorsharedsecret"
+                },
+                "master_key": {
+                  "user_id": "@alice:example.com",
+                  "usage": [
+                    "master"
+                  ],
+                  "keys": {
+                    "ed25519:base64+master+public+key": "base64+master+public+key"
+                  }
+                },
+                "self_signing_key": {
+                  "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_key": {
+                  "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"
+                    }
+                  }
+                }
+              }
+        description: The keys to be published.
+        required: true
+      responses:
+        "200":
+          description: The provided keys were successfully uploaded.
+          content:
+            application/json:
+              schema:
+                type: object
+                example: {}
+        "400":
+          description: |-
+            The input was invalid in some way. This can include one of the
+            following error codes:
+
+            * `M_INVALID_SIGNATURE`: For example, the self-signing or
+              user-signing key had an incorrect signature.
+            * `M_MISSING_PARAM`: No master signing key is available.
+          content:
+            application/json:
+              schema:
+                type: object
+                example: {
+                  "errcode": "M_INVALID_SIGNATURE",
+                  "error": "Invalid signature"
+                }
+        "403":
+          description: |-
+            The public key of one of the keys is the same as one of the user\'s
+            device IDs, or the request is not authorized for any other reason.
+          content:
+            application/json:
+              schema:
+                type: object
+                example: {
+                  "errcode": "M_FORBIDDEN",
+                  "error": "Key ID in use"
+                }
+      tags:
+        - End-to-end encryption
+  /keys/signatures/upload:
+    post:
+      x-addedInMatrixVersion: "1.1"
+      summary: Upload cross-signing signatures.
+      description: |-
+        Publishes cross-signing signatures for the user.
+
+        The signed JSON object must match the key previously uploaded or
+        retrieved for the given key ID, with the exception of the `signatures`
+        property, which contains the new signature(s) to add.
+      operationId: uploadCrossSigningSignatures
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              description: |-
+                A map of user ID to a map of key ID to signed JSON object.
+              patternProperties:
+                "^@":
+                  x-pattern-format: mx-user-id
+                  type: object
+                  additionalProperties:
+                    type: object
+              example: {
+                "@alice:example.com": {
+                  "HIJKLMN": {
+                    "user_id": "@alice:example.com",
+                    "device_id": "HIJKLMN",
+                    "algorithms": [
+                      "m.olm.v1.curve25519-aes-sha256",
+                      "m.megolm.v1.aes-sha"
+                    ],
+                    "keys": {
+                      "curve25519:HIJKLMN": "base64+curve25519+key",
+                      "ed25519:HIJKLMN": "base64+ed25519+key"
+                    },
+                    "signatures": {
+                      "@alice:example.com": {
+                        "ed25519:base64+self+signing+public+key": "base64+signature+of+HIJKLMN"
+                      }
+                    }
+                  },
+                  "base64+master+public+key": {
+                    "user_id": "@alice:example.com",
+                    "usage": [
+                      "master"
+                    ],
+                    "keys": {
+                      "ed25519:base64+master+public+key": "base64+master+public+key"
+                    },
+                    "signatures": {
+                      "@alice:example.com": {
+                        "ed25519:HIJKLMN": "base64+signature+of+master+key"
+                      }
+                    }
+                  }
+                },
+                "@bob:example.com": {
+                  "bobs+base64+master+public+key": {
+                    "user_id": "@bob:example.com",
+                    "keys": {
+                      "ed25519:bobs+base64+master+public+key": "bobs+base64+master+public+key"
+                    },
+                    "usage": [
+                      "master"
+                    ],
+                    "signatures": {
+                      "@alice:example.com": {
+                        "ed25519:base64+user+signing+public+key": "base64+signature+of+bobs+master+key"
+                      }
+                    }
+                  }
+                }
+              }
+        description: |-
+          A map from user ID to key ID to signed JSON objects containing the
+          signatures to be published.
+        required: true
+      responses:
+        "200":
+          description: The provided signatures were processed.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  failures:
+                    type: object
+                    description: |-
+                      A map from user ID to key ID to an error for any signatures
+                      that failed.  If a signature was invalid, the `errcode` will
+                      be set to `M_INVALID_SIGNATURE`.
+                    patternProperties:
+                      "^@":
+                        type: object
+                        x-pattern-format: mx-user-id
+                        additionalProperties:
+                          type: object
+                          title: Error
+                    example:
+                      "@alice:example.com":
+                        HIJKLMN:
+                          errcode: M_INVALID_SIGNATURE
+                          error: Invalid signature
+      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/definitions/auth_data.yaml

@@ -0,0 +1,34 @@
+# 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.
+title: Authentication Data
+description: |-
+  Used by clients to submit authentication information to the interactive-authentication API
+type: object
+properties:
+  type:
+    description: |-
+      The authentication type that the client is attempting to complete.
+      May be omitted if `session` is given, and the client is reissuing a
+      request which it believes has been completed out-of-band (for example,
+      via the [fallback mechanism](/client-server-api/#fallback)).
+    type: string
+  session:
+    description: The value of the session key given by the homeserver.
+    type: string
+additionalProperties:
+  description: Keys dependent on the login type
+example:
+  type: "example.type.foo"
+  session: "xxxxx"
+  example_credential: "verypoorsharedsecret"