async-matrix 0.1.2 → 1.0.0

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

@@ -0,0 +1,488 @@
+# 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 Registration API
+  version: 1.0.0
+paths:
+  /register:
+    post:
+      summary: Register for an account on this homeserver.
+      description: |-
+        This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api), except in
+        the cases where a guest account is being registered.
+
+        Register for an account on this homeserver.
+
+        There are two kinds of user account:
+
+        - `user` accounts. These accounts may use the full API described in this specification.
+
+        - `guest` accounts. These accounts may have limited permissions and may not be supported by all servers.
+
+        If registration is successful, this endpoint will issue an access token
+        the client can use to authorize itself in subsequent requests.
+
+        If the client does not supply a `device_id`, the server must
+        auto-generate one.
+
+        The server SHOULD register an account with a User ID based on the
+        `username` provided, if any. Note that the grammar of Matrix User ID
+        localparts is restricted, so the server MUST either map the provided
+        `username` onto a `user_id` in a logical manner, or reject any
+        `username` which does not comply to the grammar with
+        `M_INVALID_USERNAME`.
+
+        Matrix clients MUST NOT assume that localpart of the registered
+        `user_id` matches the provided `username`.
+
+        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).
+
+        When registering a guest account, all parameters in the request body
+        with the exception of `initial_device_display_name` MUST BE ignored
+        by the server. The server MUST pick a `device_id` for the account
+        regardless of input.
+
+        Any user ID returned by this API must conform to the grammar given in the
+        [Matrix specification](/appendices/#user-identifiers).
+
+        {{% boxes/note %}}
+        {{% added-in v="1.17" %}}
+        Even if the server doesn't support the Legacy authentication API, it
+        MUST support this endpoint for application services to be able to
+        [create users](/application-service-api/#server-admin-style-permissions).
+
+        In that case application services MUST set the `"inhibit_login": true`
+        parameter as they cannot use it to log in as users. If the
+        `inhibit_login` parameter is not set to `true`, the server MUST return a
+        400 HTTP status code with an `M_APPSERVICE_LOGIN_UNSUPPORTED` error code.
+        {{% /boxes/note %}}
+
+        {{% boxes/warning %}}
+        {{% added-in v="1.18" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients)
+        MUST NOT use this endpoint when the server offers the [`m.login.sso`
+        authentication flow](/client-server-api/#client-login-via-sso) with
+        `oauth_aware_preferred` set to `true`. Instead they MUST use the
+        [`/login/sso/redirect`](/client-server-api/#get_matrixclientv3loginssoredirect)
+        endpoint, adding the `action=register` parameter.
+        {{% /boxes/warning %}}
+      operationId: register
+      parameters:
+        - in: query
+          name: kind
+          required: false
+          description: The kind of account to register. Defaults to `user`.
+          # swagger-UI overrides the default with the example, so better make the
+          # example the default.
+          example: user
+          schema:
+            type: string
+            enum:
+              - guest
+              - user
+            default: user
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                auth:
+                  description: |-
+                    Additional authentication information for the
+                    user-interactive authentication API. Note that this
+                    information is *not* used to define how the registered user
+                    should be authenticated, but is instead used to
+                    authenticate the `register` call itself.
+                  allOf:
+                    - $ref: definitions/auth_data.yaml
+                username:
+                  type: string
+                  description: |-
+                    The basis for the localpart of the desired Matrix ID. If omitted,
+                    the homeserver MUST generate a Matrix ID local part.
+                  example: cheeky_monkey
+                password:
+                  type: string
+                  description: The desired password for the account.
+                  example: ilovebananas
+                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 server
+                    will auto-generate a `device_id` if this is not specified.
+                  example: GHTYAJCE
+                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.
+                  example: Jungle Phone
+                inhibit_login:
+                  type: boolean
+                  description: |-
+                    If true, an `access_token` and `device_id` should not be
+                    returned from this call, therefore preventing an automatic
+                    login. Defaults to `false`.
+                  example: false
+                refresh_token:
+                  type: boolean
+                  description: If `true`, the client supports refresh tokens.
+                  x-addedInMatrixVersion: "1.3"
+        required: true
+      responses:
+        "200":
+          description: The account has been registered.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  user_id:
+                    type: string
+                    format: mx-user-id
+                    pattern: "^@"
+                    description: |-
+                      The fully-qualified Matrix user ID (MXID) that has been registered.
+
+                      Any user ID returned by this API must conform to the grammar given in the
+                      [Matrix specification](/appendices/#user-identifiers).
+                  access_token:
+                    type: string
+                    description: |-
+                      An access token for the account.
+                      This access token can then be used to authorize other requests.
+                      Required if the `inhibit_login` option is false.
+                  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.
+
+                      Omitted if the `inhibit_login` option is true.
+                    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.
+
+                      Omitted if the `inhibit_login` option is true.
+                    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 registered device. Will be the same as the
+                      corresponding parameter in the request, if one was specified.
+                      Required if the `inhibit_login` option is false.
+                required:
+                  - user_id
+              examples:
+                response:
+                  value: {
+                    "user_id": "@cheeky_monkey:matrix.org",
+                    "access_token": "abc123",
+                    "device_id": "GHTYAJCE"
+                  }
+        "400":
+          description: |-
+            Part of the request was invalid. This may include one of the following error codes:
+
+            * `M_USER_IN_USE` : The desired user ID is already taken.
+            * `M_INVALID_USERNAME` : The desired user ID is not a valid user name.
+            * `M_EXCLUSIVE` : The desired user ID is in the exclusive namespace
+              claimed by an application service.
+            * {{% added-in v="1.17" %}} `M_APPSERVICE_LOGIN_UNSUPPORTED`: an application service
+              used the `m.login.application_service` type without setting `inhibit_login` to `true`,
+              but the server doesn't support logging in via the Legacy authentication API.
+
+            These errors may be returned at any stage of the registration process,
+            including after authentication if the requested user ID was registered
+            whilst the client was performing authentication.
+
+            Homeservers MUST perform the relevant checks and return these codes before
+            performing User-Interactive Authentication, although they may also return
+            them after authentication is completed if, for example, the requested user ID
+            was registered whilst the client was performing authentication.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_USER_IN_USE",
+                    "error": "Desired user ID is already taken."
+                  }
+        "401":
+          description: The homeserver requires additional authentication information.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/auth_response.yaml
+        "403":
+          description: |-
+            The homeserver does not permit registering the account. This response
+            can be used to identify that a particular `kind` of account is not
+            allowed, or that registration is generally not supported by the homeserver.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "Registration is disabled"
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - Account management
+  /register/email/requestToken:
+    post:
+      summary: Begins the validation process for an email to be used during
+        registration.
+      description: |-
+        The homeserver must check that the given email address is **not**
+        already associated with an account on this homeserver. The homeserver
+        should validate the email itself, either by sending a validation email
+        itself or by using a service it has control over.
+      operationId: requestTokenToRegisterEmail
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: definitions/request_email_validation.yaml
+        required: true
+      responses:
+        "200":
+          description: |-
+            An email has been sent to the specified address. Note that this
+            may be an email containing the validation token or it may be
+            informing the user of an error.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/request_token_response.yaml
+        "400":
+          description: |-
+            Part of the request was invalid. This may include one of the following error codes:
+
+            * `M_THREEPID_IN_USE` : The email address is already registered to an account on this server.
+              However, if the homeserver has the ability to send email, it is recommended that the server
+              instead send an email to the user with instructions on how to reset their password.
+              This prevents malicious parties from being able to determine if a given email address
+              has an account on the homeserver in question.
+            * `M_SERVER_NOT_TRUSTED` : The `id_server` parameter refers to an identity server
+              that is not trusted by this homeserver.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_THREEPID_IN_USE",
+                    "error": "The specified address is already in use"
+                  }
+        "403":
+          description: The homeserver does not permit the address to be bound.
+          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
+  /register/msisdn/requestToken:
+    post:
+      summary: Requests a validation token be sent to the given phone number for the
+        purpose of registering an account
+      description: |-
+        The homeserver must check that the given phone number is **not**
+        already associated with an account on this homeserver. 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: requestTokenToRegisterMSISDN
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: definitions/request_msisdn_validation.yaml
+        required: true
+      responses:
+        "200":
+          description: |-
+            An SMS message has been sent to the specified phone number. Note
+            that this may be an SMS message containing the validation token or
+            it may be informing the user of an error.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/request_token_response.yaml
+        "400":
+          description: |-
+            Part of the request was invalid. This may include one of the following error codes:
+
+            * `M_THREEPID_IN_USE` : The phone number is already registered to an account on this server.
+              However, if the homeserver has the ability to send SMS message, it is recommended that the server
+              instead send an SMS message to the user with instructions on how to reset their password.
+              This prevents malicious parties from being able to determine if a given phone number
+              has an account on the homeserver in question.
+            * `M_SERVER_NOT_TRUSTED` : The `id_server` parameter refers to an identity server
+              that is not trusted by this homeserver.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_THREEPID_IN_USE",
+                    "error": "The specified address is already in use"
+                  }
+        "403":
+          description: The homeserver does not permit the address to be bound.
+          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
+  /register/available:
+    get:
+      summary: Checks to see if a username is available on the server.
+      description: |-
+        Checks to see if a username is available, and valid, for the server.
+
+        The server should check to ensure that, at the time of the request, the
+        username requested is available for use. This includes verifying that an
+        application service has not claimed the username and that the username
+        fits the server's desired requirements (for example, a server could dictate
+        that it does not permit usernames with underscores).
+
+        Matrix clients may wish to use this API prior to attempting registration,
+        however the clients must also be aware that using this API does not normally
+        reserve the username. This can mean that the username becomes unavailable
+        between checking its availability and attempting to register it.
+      operationId: checkUsernameAvailability
+      parameters:
+        - in: query
+          name: username
+          required: true
+          description: The username to check the availability of.
+          example: my_cool_localpart
+          schema:
+            type: string
+            default: my_cool_localpart
+      responses:
+        "200":
+          description: The username is available
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  available:
+                    type: boolean
+                    description: |-
+                      A flag to indicate that the username is available. This should always
+                      be `true` when the server replies with 200 OK.
+              examples:
+                response:
+                  value: {
+                    "available": true
+                  }
+        "400":
+          description: |-
+            Part of the request was invalid or the username is not available. This may
+            include one of the following error codes:
+
+            * `M_USER_IN_USE` : The desired username is already taken.
+            * `M_INVALID_USERNAME` : The desired username is not a valid user name.
+            * `M_EXCLUSIVE` : The desired username is in the exclusive namespace
+              claimed by an application service.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_USER_IN_USE",
+                    "error": "Desired user ID is already taken."
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      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/registration_tokens.yaml

@@ -0,0 +1,93 @@
+# 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 Token API
+  version: 1.0.0
+paths:
+  /register/m.login.registration_token/validity:
+    get:
+      x-addedInMatrixVersion: "1.2"
+      summary: Query if a given registration token is still valid.
+      description: |-
+        Queries the server to determine if a given registration token is still
+        valid at the time of request. This is a point-in-time check where the
+        token might still expire by the time it is used.
+
+        Servers should be sure to rate limit this endpoint to avoid brute force
+        attacks.
+      operationId: registrationTokenValidity
+      parameters:
+        - in: query
+          name: token
+          required: true
+          description: The token to check validity of.
+          example: fBVFdqVE
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The check has a result.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  valid:
+                    type: boolean
+                    description: |-
+                      True if the token is still valid, false otherwise. This should
+                      additionally be false if the token is not a recognised token by
+                      the server.
+                required:
+                  - valid
+              examples:
+                response:
+                  value: {
+                    "valid": true
+                  }
+        "403":
+          description: |-
+            The homeserver does not permit registration and thus all tokens are
+            considered invalid.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "Registration is not enabled on this homeserver."
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - Account management
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v1