async-matrix 0.1.2 → 1.0.0

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

@@ -0,0 +1,321 @@
+# Copyright 2016 OpenMarket Ltd
+# Copyright 2018 New Vector 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 Registration and Login API
+  version: 1.0.0
+paths:
+  /login:
+    get:
+      summary: Get the supported login types to authenticate users
+      description: |-
+        Gets the homeserver's supported login types to authenticate users. Clients
+        should pick one of these and supply it as the `type` when logging in.
+      operationId: getLoginFlows
+      responses:
+        "200":
+          description: The login types the homeserver supports
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  flows:
+                    type: array
+                    description: The homeserver's supported login types
+                    items:
+                      type: object
+                      title: LoginFlow
+                      required:
+                        - type
+                      properties:
+                        type:
+                          description: |-
+                            The login type. This is supplied as the `type` when
+                            logging in.
+                          type: string
+                        get_login_token:
+                          type: boolean
+                          x-addedInMatrixVersion: "1.7"
+                          description: |-
+                            If `type` is `m.login.token`, an optional field to indicate
+                            to the unauthenticated client that the homeserver supports
+                            the [`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token)
+                            endpoint. Note that supporting the endpoint does not
+                            necessarily indicate that the user attempting to log in will
+                            be able to generate such a token.
+              examples:
+                response:
+                  value: {
+                    "flows": [
+                      {
+                        "type": "m.login.password"
+                      },
+                      {
+                        "type": "m.login.token",
+                        "get_login_token": true
+                      }
+                    ]
+                  }
+        "404":
+          description: |-
+            With `M_UNRECOGNIZED`: the homeserver does not support the legacy authentication API.
+            (See [Authentication API discovery](/client-server-api/#authentication-api-discovery).)
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value:
+                    {
+                      "errcode": "M_UNRECOGNIZED",
+                      "error": "OAuth 2.0 authentication is in use on this homeserver.",
+                    }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - Session management
+    post:
+      summary: Authenticates the user.
+      description: |-
+        Authenticates the user, and issues an access token they can
+        use to authorize themself in subsequent requests.
+
+        If the client does not supply a `device_id`, the server must
+        auto-generate one.
+
+        The returned access token must be associated with the `device_id`
+        supplied by the client or generated by the server. The server may
+        invalidate any access token previously associated with that device. See
+        [Relationship between access tokens and devices](/client-server-api/#relationship-between-access-tokens-and-devices).
+      operationId: login
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              example: {
+                "type": "m.login.password",
+                "identifier": {
+                  "type": "m.id.user",
+                  "user": "cheeky_monkey"
+                },
+                "password": "ilovebananas",
+                "initial_device_display_name": "Jungle Phone"
+              }
+              properties:
+                type:
+                  type: string
+                  description: |-
+                    The login type being used.
+
+                    This must be a type returned in one of the flows of the
+                    response of the [`GET /login`](/client-server-api/#get_matrixclientv3login)
+                    endpoint, like `m.login.password` or `m.login.token`.
+                identifier:
+                  $ref: definitions/user_identifier.yaml
+                user:
+                  type: string
+                  deprecated: true
+                  description: The fully qualified user ID or just local part of the user ID, to
+                    log in.  Deprecated in favour of `identifier`.
+                medium:
+                  type: string
+                  deprecated: true
+                  description: When logging in using a third-party identifier, the medium of the
+                    identifier. Must be 'email'.  Deprecated in favour of
+                    `identifier`.
+                address:
+                  type: string
+                  deprecated: true
+                  description: Third-party identifier for the user.  Deprecated in favour of
+                    `identifier`.
+                password:
+                  type: string
+                  description: |-
+                    Required when `type` is `m.login.password`. The user's
+                    password.
+                token:
+                  type: string
+                  description: Required when `type` is `m.login.token`. Part of Token-based login.
+                device_id:
+                  type: string
+                  description: |-
+                    ID of the client device. If this does not correspond to a
+                    known client device, a new device will be created. The given
+                    device ID must not be the same as a
+                    [cross-signing](/client-server-api/#cross-signing) key ID.
+                    The server will auto-generate a `device_id`
+                    if this is not specified.
+                initial_device_display_name:
+                  type: string
+                  description: |-
+                    A display name to assign to the newly-created device. Ignored
+                    if `device_id` corresponds to a known device.
+                refresh_token:
+                  type: boolean
+                  description: If true, the client supports refresh tokens.
+                  x-addedInMatrixVersion: "1.3"
+              required:
+                - type
+        required: true
+      responses:
+        "200":
+          description: The user has been authenticated.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  user_id:
+                    type: string
+                    format: mx-user-id
+                    pattern: "^@"
+                    description: The fully-qualified Matrix ID for the account.
+                  access_token:
+                    type: string
+                    description: |-
+                      An access token for the account.
+                      This access token can then be used to authorize other requests.
+                  refresh_token:
+                    type: string
+                    description: |-
+                      A refresh token for the account. This token can be used to
+                      obtain a new access token when it expires by calling the
+                      `/refresh` endpoint.
+                    x-addedInMatrixVersion: "1.3"
+                  expires_in_ms:
+                    type: integer
+                    description: |-
+                      The lifetime of the access token, in milliseconds. Once
+                      the access token has expired a new access token can be
+                      obtained by using the provided refresh token. If no
+                      refresh token is provided, the client will need to re-log in
+                      to obtain a new access token. If not given, the client can
+                      assume that the access token will not expire.
+                    x-addedInMatrixVersion: "1.3"
+                  home_server:
+                    type: string
+                    format: mx-server-name
+                    deprecated: true
+                    description: |-
+                      The server_name of the homeserver on which the account has
+                      been registered.
+
+                      **Deprecated**. Clients should extract the server_name from
+                      `user_id` (by splitting at the first colon) if they require
+                      it. Note also that `homeserver` is not spelt this way.
+                  device_id:
+                    type: string
+                    description: |-
+                      ID of the logged-in device. Will be the same as the
+                      corresponding parameter in the request, if one was specified.
+                  well_known:
+                    description: |-
+                      Optional client configuration provided by the server. If present,
+                      clients SHOULD use the provided object to reconfigure themselves,
+                      optionally validating the URLs within. This object takes the same
+                      form as the one returned from .well-known autodiscovery.
+                    allOf:
+                      - $ref: definitions/wellknown/full.yaml
+                required:
+                  - access_token
+                  - device_id
+                  - user_id
+              examples:
+                response:
+                  value: {
+                    "user_id": "@cheeky_monkey:matrix.org",
+                    "access_token": "abc123",
+                    "refresh_token": "def456",
+                    "expires_in_ms": 60000,
+                    "device_id": "GHTYAJCE",
+                    "well_known": {
+                      "m.homeserver": {
+                        "base_url": "https://example.org"
+                      },
+                      "m.identity_server": {
+                        "base_url": "https://id.example.org"
+                      }
+                    }
+                  }
+        "400":
+          description: |-
+            Part of the request was invalid. For example, the login type may not be recognised.
+
+            Specific error codes used with this status code include:
+              * {{% added-in v="1.17" %}} `M_APPSERVICE_LOGIN_UNSUPPORTED`: an application service
+                used the `m.login.application_service` type, but the server doesn't support logging
+                in via the Legacy authentication API.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_UNKNOWN",
+                    "error": "Bad login type."
+                  }
+        "403":
+          description: |-
+            The login attempt failed. This can include one of the following error codes:
+              * `M_FORBIDDEN`: The provided authentication data was incorrect
+                or the requested device ID is the same as a cross-signing key
+                ID.
+              * `M_USER_DEACTIVATED`: The user has been deactivated.
+                Servers MAY instead use `M_FORBIDDEN` when they can no longer authenticate
+                the deactivated user (e.g. their password has been wiped).
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN"
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - Session 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/login_token.yaml

@@ -0,0 +1,138 @@
+# Copyright 2023 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 Registration and Login API
+  version: 1.0.0
+paths:
+  /login/get_token:
+    post:
+      summary: Optional endpoint to generate a single-use, time-limited,
+        `m.login.token` token.
+      description: |-
+        Optional endpoint - the server is not required to implement this endpoint if it does not
+        intend to use or support this functionality.
+
+        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
+
+        An already-authenticated client can call this endpoint to generate a single-use, time-limited,
+        token for an unauthenticated client to log in with, becoming logged in as the same user which
+        called this endpoint. The unauthenticated client uses the generated token in a `m.login.token`
+        login flow with the homeserver.
+
+        Clients, both authenticated and unauthenticated, might wish to hide user interface which exposes
+        this feature if the server is not offering it. Authenticated clients can check for support on
+        a per-user basis with the [`m.get_login_token`](/client-server-api/#mget_login_token-capability) capability,
+        while unauthenticated clients can detect server support by looking for an `m.login.token` login
+        flow with `get_login_token: true` on [`GET /login`](/client-server-api/#post_matrixclientv3login).
+
+        In v1.7 of the specification, transmission of the generated token to an unauthenticated client is
+        left as an implementation detail. Future MSCs such as [MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/3906)
+        might standardise a way to transmit the token between clients.
+
+        The generated token MUST only be valid for a single login, enforced by the server. Clients which
+        intend to log in multiple devices must generate a token for each.
+
+        With other User-Interactive Authentication (UIA)-supporting endpoints, servers sometimes do not re-prompt
+        for verification if the session recently passed UIA. For this endpoint, servers MUST always re-prompt
+        the user for verification to ensure explicit consent is gained for each additional client.
+
+        Servers are encouraged to apply stricter than normal rate limiting to this endpoint, such as maximum
+        of 1 request per minute.
+      operationId: generateLoginToken
+      x-addedInMatrixVersion: "1.7"
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                auth:
+                  description: Additional authentication information for the user-interactive
+                    authentication API.
+                  allOf:
+                    - $ref: definitions/auth_data.yaml
+        required: true
+      responses:
+        "200":
+          description: The login token an unauthenticated client can use to log in as the
+            requesting user.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - login_token
+                  - expires_in_ms
+                properties:
+                  login_token:
+                    type: string
+                    description: The login token for the `m.login.token` login flow.
+                  expires_in_ms:
+                    type: integer
+                    description: |-
+                      The time remaining in milliseconds until the homeserver will no longer accept the token. `120000`
+                      (2 minutes) is recommended as a default.
+              examples:
+                response:
+                  value: {
+                    "login_token": "<opaque string>",
+                    "expires_in_ms": 120000
+                  }
+        "400":
+          description: |-
+            The request was malformed, or the user does not have an ability to generate tokens for their devices,
+            as implied by the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
+
+            Clients should verify whether the user has an ability to call this endpoint with the
+            [`m.get_login_token`](/client-server-api/#mget_login_token-capability) capability.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+        "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:
+        - Session management
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v1
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

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

@@ -0,0 +1,86 @@
+# 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 Registration and Login API
+  version: 1.0.0
+paths:
+  /logout:
+    post:
+      summary: Invalidates a user access token
+      description: |-
+        Invalidates an existing access token, so that it can no longer be used for
+        authorization. The device associated with the access token is also deleted.
+        [Device keys](/client-server-api/#device-keys) for the device are deleted alongside the device.
+      operationId: logout
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      responses:
+        "200":
+          description: The access token used in the request was successfully invalidated.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties: {}
+      tags:
+        - Session management
+  /logout/all:
+    post:
+      summary: Invalidates all access tokens for a user
+      description: |-
+        Invalidates all access tokens for a user, so that they can no longer be used for
+        authorization. This includes the access token that made this request. All devices
+        for the user are also deleted. [Device keys](/client-server-api/#device-keys) for the device are
+        deleted alongside the device.
+
+        This endpoint does not use the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api) because
+        User-Interactive Authentication is designed to protect against attacks where
+        someone gets hold of a single access token then takes over the account. This
+        endpoint invalidates all access tokens for the user, including the token used in
+        the request, and therefore the attacker is unable to take over the account in
+        this way.
+      operationId: logout_all
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      responses:
+        "200":
+          description: The user's access tokens were successfully invalidated.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties: {}
+      tags:
+        - Session 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