async-matrix 0.1.2 → 1.0.0

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

@@ -0,0 +1,246 @@
+# Copyright 2016 OpenMarket Ltd
+# Copyright 2022 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 Password Management API
+  version: 1.0.0
+paths:
+  /account/password:
+    post:
+      summary: Changes a user's password.
+      description: |-
+        Changes the password for an account on this homeserver.
+
+        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api) to
+        ensure the user changing the password is actually the owner of the
+        account.
+
+        An access token should be submitted to this endpoint if the client has
+        an active session.
+
+        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. Whether other access tokens for
+        the user are revoked depends on the request parameters.
+
+        This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation).
+        Clients SHOULD check the value of the [`m.change_password` capability](/client-server-api/#mchange_password-capability)
+        to determine if this endpoint is available.
+      security:
+        - {}
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      operationId: changePassword
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                new_password:
+                  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](/client-server-api/#soft-logout)
+                    for the user's remaining devices.
+                  example: true
+                auth:
+                  description: Additional authentication information for the user-interactive
+                    authentication API.
+                  allOf:
+                    - $ref: definitions/auth_data.yaml
+              required:
+                - new_password
+        required: true
+      responses:
+        "200":
+          description: The password has been changed.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+        "401":
+          description: The homeserver requires additional authentication information.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/auth_response.yaml
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - Account management
+  /account/password/email/requestToken:
+    post:
+      summary: Requests a validation token be sent to the given email address for the
+        purpose of resetting a user's password
+      description: |-
+        The homeserver must check that the given email address **is
+        associated** with an account on this homeserver. This API should be
+        used to request validation tokens when authenticating for the
+        `/account/password` endpoint.
+
+        This API's parameters and response are identical to that of the
+        [`/register/email/requestToken`](/client-server-api/#post_matrixclientv3registeremailrequesttoken)
+        endpoint, except that
+        `M_THREEPID_NOT_FOUND` may be returned if no account matching the
+        given email address could be found. The server may instead send an
+        email to the given address prompting the user to create an account.
+        `M_THREEPID_IN_USE` may not be returned.
+
+        The homeserver should validate the email itself, either by sending a
+        validation email itself or by using a service it has control over.
+      operationId: requestTokenToResetPasswordEmail
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: definitions/request_email_validation.yaml
+        required: true
+      responses:
+        "200":
+          description: An email was sent to the given address.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/request_token_response.yaml
+        "400":
+          description: |-
+            The referenced third-party identifier is not recognised by the
+            homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
+            can be returned if the server does not trust/support the identity server
+            provided in the request.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_THREEPID_NOT_FOUND",
+                    "error": "Email not found"
+                  }
+        "403":
+          description: |-
+            The homeserver does not allow the third-party identifier as a
+            contact option.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_THREEPID_DENIED",
+                    "error": "Third-party identifier is not allowed"
+                  }
+      tags:
+        - Account management
+  /account/password/msisdn/requestToken:
+    post:
+      summary: Requests a validation token be sent to the given phone number for the
+        purpose of resetting a user's password.
+      description: |-
+        The homeserver must check that the given phone number **is
+        associated** with an account on this homeserver. This API should be
+        used to request validation tokens when authenticating for the
+        `/account/password` endpoint.
+
+        This API's parameters and response are identical to that of the
+        [`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientv3registermsisdnrequesttoken)
+        endpoint, except that
+        `M_THREEPID_NOT_FOUND` may be returned if no account matching the
+        given phone number could be found. The server may instead send the SMS
+        to the given phone number prompting the user to create an account.
+        `M_THREEPID_IN_USE` may not be returned.
+
+        The homeserver should validate the phone number itself, either by sending a
+        validation message itself or by using a service it has control over.
+      operationId: requestTokenToResetPasswordMSISDN
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: definitions/request_msisdn_validation.yaml
+        required: true
+      responses:
+        "200":
+          description: An SMS message was sent to the given phone number.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/request_token_response.yaml
+        "400":
+          description: |-
+            The referenced third-party identifier is not recognised by the
+            homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
+            can be returned if the server does not trust/support the identity server
+            provided in the request.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_THREEPID_NOT_FOUND",
+                    "error": "Phone number not found"
+                  }
+        "403":
+          description: |-
+            The homeserver does not allow the third-party identifier as a
+            contact option.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_THREEPID_DENIED",
+                    "error": "Third-party identifier is not allowed"
+                  }
+      tags:
+        - Account management
+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/peeking_events.yaml

@@ -0,0 +1,122 @@
+# 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 Sync Guest API
+  version: 1.0.0
+paths:
+  # With an extra " " to disambiguate from the getEvents endpoint
+  # The extra space makes it sort first for what I'm sure is a good reason.
+  "/events ":
+    get:
+      summary: Listen on the event stream of a particular room.
+      description: |-
+        This will listen for new events related to a particular room and return
+        them to the caller. This will block until an event is received, or until
+        the `timeout` is reached.
+
+        This API is the same as the normal `/events` endpoint, but can be
+        called by users who have not joined the room.
+
+        Note that the normal `/events` endpoint has been deprecated. This
+        API will also be deprecated at some point, but its replacement is not
+        yet known.
+      operationId: peekEvents
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: query
+          name: from
+          description: |-
+            The token to stream from. This token is either from a previous
+            request to this API or from the initial sync API.
+          required: false
+          example: s3456_9_0
+          schema:
+            type: string
+        - in: query
+          name: timeout
+          description: The maximum time in milliseconds to wait for an event.
+          required: false
+          example: 35000
+          schema:
+            type: integer
+        - in: query
+          name: room_id
+          description: The room ID for which events should be returned.
+          example: "!somewhere:over.the.rainbow"
+          schema:
+            type: string
+          required: true
+      responses:
+        "200":
+          description: The events received, which may be none.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  start:
+                    type: string
+                    description: |-
+                      A token which correlates to the first value in `chunk`. This
+                      is usually the same token supplied to `from=`.
+                  end:
+                    type: string
+                    description: |-
+                      A token which correlates to the last value in `chunk`. This
+                      token should be used in the next request to `/events`.
+                  chunk:
+                    type: array
+                    description: An array of events.
+                    items:
+                      type: object
+                      title: Event
+                      allOf:
+                        - $ref: definitions/client_event.yaml
+              examples:
+                response:
+                  value: {
+                    "start": "s3456_9_0",
+                    "end": "s3457_9_0",
+                    "chunk": [
+                      {
+                        "room_id": "!somewhere:over.the.rainbow",
+                        "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
+                      }
+                    ]
+                  }
+        "400":
+          description: Bad pagination `from` parameter.
+      tags:
+        - Room participation
+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/policy_server.yaml

@@ -0,0 +1,82 @@
+# Copyright 2026 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 Policy Server Discovery API
+  version: 1.0.0
+paths:
+  /matrix/policy_server:
+    get:
+      summary: Gets information about a Policy Server's configuration, if available.
+      description: |-
+        Gets public key information for a [Policy Server](/client-server-api/#policy-servers).
+
+        {{% boxes/note %}}
+        Like the [well-known discovery URI](/client-server-api/#well-known-uris),
+        this endpoint should be accessed with the hostname of the Policy Server's
+        [server name](/appendices/#server-name) by making a
+        GET request to `https://hostname/.well-known/matrix/policy_server`.
+        {{% /boxes/note %}}
+
+        Note that this endpoint is not necessarily handled by the homeserver or
+        Policy Server. It may be served by another webserver.
+      operationId: getWellknownPolicy
+      x-addedInMatrixVersion: "1.18"
+      responses:
+        "200":
+          description: |-
+            Public keys for the Policy Server. Can be supplied to the [`m.room.policy`](/client-server-api/#mroompolicy)
+            state event.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  public_keys:
+                    type: object
+                    description: |-
+                      The unpadded base64-encoded public keys for the Policy Server. MUST contain
+                      at least `ed25519`.
+                    properties:
+                      ed25519:
+                        type: string
+                        description: The unpadded base64-encoded ed25519 public key for the Policy Server.
+                    required: ['ed25519']
+                    additionalProperties:
+                      type: string
+                      description: The unpadded base64-encoded public key for the key algorithm.
+                required: ["public_keys"]
+              examples:
+                response:
+                  value:
+                    {
+                      "public_keys": {
+                        "ed25519": "6yhHGKhCiXTSEN2ksjV7kX_N6rBQZ3Xb-M7LlC6NS-s"
+                      }
+                    }
+        "404":
+          description: No policy server information available.
+      tags:
+        - Server administration
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /.well-known

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

@@ -0,0 +1,169 @@
+# 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 Presence API
+  version: 1.0.0
+paths:
+  "/presence/{userId}/status":
+    put:
+      summary: Update this user's presence state.
+      description: |-
+        This API sets the given user's presence state. When setting the status,
+        the activity time is updated to reflect that activity; the client does
+        not need to specify the `last_active_ago` field. You cannot set the
+        presence state of another user.
+      operationId: setPresence
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: userId
+          description: The user whose presence state to update.
+          required: true
+          example: "@alice:example.com"
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              example: {
+                "presence": "online",
+                "status_msg": "I am here."
+              }
+              properties:
+                presence:
+                  type: string
+                  enum:
+                    - online
+                    - offline
+                    - unavailable
+                  description: The new presence state.
+                status_msg:
+                  type: string
+                  description: The status message to attach to this state.
+              required:
+                - presence
+        description: The updated presence state.
+        required: true
+      responses:
+        "200":
+          description: The new presence state was set.
+          content:
+            application/json:
+              schema:
+                type: object  # empty json object
+              examples:
+                response:
+                  value: {}
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - Presence
+    get:
+      summary: Get this user's presence state.
+      description: Get the given user's presence state.
+      operationId: getPresence
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: userId
+          description: The user whose presence state to get.
+          required: true
+          example: "@alice:example.com"
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The presence state for this user.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  presence:
+                    type: string
+                    enum:
+                      - online
+                      - offline
+                      - unavailable
+                    description: This user's presence.
+                  last_active_ago:
+                    type: integer
+                    description: |-
+                      The length of time in milliseconds since an action was performed
+                      by this user.
+                  status_msg:
+                    description: The state message for this user if one was set.
+                    type: ["string", "null"]
+                  currently_active:
+                    type: boolean
+                    description: Whether the user is currently active
+                required:
+                  - presence
+              examples:
+                response:
+                  value: {
+                    "presence": "unavailable",
+                    "last_active_ago": 420845
+                  }
+        "403":
+          description: You are not allowed to see this user's presence status.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "You are not allowed to see their presence"
+                  }
+        "404":
+          description: |-
+            There is no presence state for this user. This user may not exist or
+            isn't exposing presence information to you.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+      tags:
+        - Presence
+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