async-matrix 0.1.3 → 1.0.0

data/data/matrix-spec/api/client-server/definitions/key_backup_data.yaml

@@ -0,0 +1,50 @@
+# Copyright 2019 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.
+
+type: object
+title: KeyBackupData
+description: "The key data"
+properties:
+  first_message_index:
+    description: |-
+      The index of the first message in the session that the key can decrypt.
+    type: integer
+    example: 1
+  forwarded_count:
+    description: |-
+      The number of times this key has been forwarded via key-sharing between devices.
+    type: integer
+    example: 0
+  is_verified:
+    description: |-
+      Whether the device backing up the key verified the device that the key
+      is from.
+    type: boolean
+    example: false
+  session_data:
+    description: |-
+      Algorithm-dependent data.  See the documentation for the backup
+      algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the
+      expected format of the data.
+    type: object
+    example: {
+      "ephemeral": "base64+ephemeral+key",
+      "ciphertext": "base64+ciphertext+of+JSON+data",
+      "mac": "base64+mac+of+ciphertext"
+    }
+required:
+  - first_message_index
+  - forwarded_count
+  - is_verified
+  - session_data

data/data/matrix-spec/api/client-server/definitions/key_backup_session_data.yaml

@@ -0,0 +1,57 @@
+# 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.
+
+
+type: object
+title: BackedUpSessionData
+description: |-
+  The format of a backed-up session key, prior to encryption, when using the
+  `m.megolm_backup.v1.curve25519-aes-sha2` algorithm.
+properties:
+  algorithm:
+    type: string
+    description: |-
+      The end-to-end message encryption algorithm that the key is for. Must be `m.megolm.v1.aes-sha2`.
+    example: "m.megolm.v1.aes-sha2"
+  forwarding_curve25519_key_chain:
+    type: array
+    items:
+      type: string
+    description: |-
+      Chain of Curve25519 keys through which this session was forwarded, via [m.forwarded_room_key](/client-server-api/#mforwarded_room_key)
+      events.
+    example: [ "hPQNcabIABgGnx3/ACv/jmMmiQHoeFfuLB17tzWp6Hw" ]
+  sender_key:
+    type: string
+    description: |-
+      Unpadded base64-encoded device Curve25519 key.
+    example: "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU"
+  sender_claimed_keys:
+    type: object
+    additionalProperties:
+      type: string
+    description: |-
+      A map from algorithm name (`ed25519`) to the Ed25519 signing key of the sending device.
+    example: { "ed25519": "aj40p+aw64yPIdsxoog8jhPu9i7l7NcFRecuOQblE3Y" }
+  session_key:
+    type: string
+    description: |-
+      Unpadded base64-encoded session key in [session-export format](https://gitlab.matrix.org/matrix-org/olm/blob/master/docs/megolm.md#session-export-format).
+    example: "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf..."
+required:
+  - algorithm
+  - forwarding_curve25519_key_chain
+  - sender_key
+  - sender_claimed_keys
+  - session_key

data/data/matrix-spec/api/client-server/definitions/m.login.terms_params.yaml

@@ -0,0 +1,83 @@
+# Copyright 2024 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.
+
+type: object
+title: m.login.terms params
+description: Schema for `m.login.terms` entry in the `params` object in a User-Interactive Authentication response.
+required: ['policies']
+properties:
+  policies:
+    type: object
+    description: |
+      A map from "Policy ID" to the current definition of this policy document. The Policy ID is a unique
+      identifier for a given policy document, using the [Opaque Identifier Grammar](/appendices/#opaque-identifiers).
+    additionalProperties:
+      type: object
+      title: Policy Definition
+      required: [version]
+      properties:
+        version:
+          type: string
+          description: |
+            The version of this policy document. This is provided as a convenience for the client,
+            and uses the [Opaque Identifier Grammar](/appendices/#opaque-identifiers).
+      additionalProperties:
+        type: object
+        title: Policy Translation
+        required: [name, url]
+        description: |
+          Map from language codes to details of the document in that language.
+          Language codes SHOULD be formatted as per [Section 2.2 of RFC
+          5646](https://datatracker.ietf.org/doc/html/rfc5646#section-2.2),
+          though some implementations may use an underscore instead of dash
+          (for example, `en_US` instead of `en-US`).
+        properties:
+          name:
+            type: string
+            description: |
+              The name of this document, in the appropriate language. An
+              arbitrary string with no specified maximum length.
+          url:
+            type: string
+            format: uri
+            description: |
+              A link to the text of this document, in the appropriate
+              language. MUST be a valid URI with scheme `https://` or
+              `http://`. Insecure HTTP is discouraged.
+example: {
+    "policies": {
+        "terms_of_service": {
+            "version": "1.2",
+            "en": {
+                "name": "Terms of Service",
+                "url": "https://example.org/somewhere/terms-1.2-en.html"
+            },
+            "fr": {
+                "name": "Conditions d'utilisation",
+                "url": "https://example.org/somewhere/terms-1.2-fr.html"
+            }
+        },
+        "privacy_policy": {
+            "version": "1.2",
+            "en": {
+                "name": "Privacy Policy",
+                "url": "https://example.org/somewhere/privacy-1.2-en.html"
+            },
+            "fr": {
+                "name": "Politique de confidentialité",
+                "url": "https://example.org/somewhere/privacy-1.2-fr.html"
+            }
+        }
+    }
+}

data/data/matrix-spec/api/client-server/definitions/m.mentions.yaml

@@ -0,0 +1,33 @@
+# 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.
+
+type: object
+title: m.mentions
+description: |-
+  Describes whether the event mentions other users or the room. This is contained
+  within the event's `content` alongside other fields for the relevant event type.
+example: {
+    "user_ids": ["@alice:example.org"]
+}
+properties:
+  user_ids:
+    type: array
+    items:
+      type: string
+    description: A list of Matrix IDs of mentioned users.
+  room:
+    type: boolean
+    description: |-
+      A boolean set to `true` to mention the room, for an `@room` notification.
+      (`room` should otherwise not be included on the event.)

data/data/matrix-spec/api/client-server/definitions/m.oauth_params.yaml

@@ -0,0 +1,30 @@
+# Copyright 2025 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.
+
+type: object
+title: m.oauth params
+description: Schema for `m.oauth` entry in the `params` object in a User-Interactive Authentication response.
+required: ['url']
+properties:
+  url:
+    type: string
+    format: uri
+    description: |
+      A URL pointing to the homeserver's OAuth account management web UI
+      where the user can approve the action. MUST be a valid URI with scheme
+      `http://` or `https://`, the latter being RECOMMENDED.
+    pattern: "^https?://"
+example: {
+    "url": "https://example.org/account/reset-cross-signing"
+}

data/data/matrix-spec/api/client-server/definitions/m.relates_to.yaml

@@ -0,0 +1,45 @@
+# 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.
+
+type: object
+title: m.relates_to
+description: |-
+  Describes the relationship of an event to its parent. This is contained
+  within the event's `content` alongside other fields for the relevant event type.
+example: {
+  # We deliberately "break" the example by including the top-level field so it renders
+  # sensibly for readers of the spec.
+  "m.relates_to": {
+    "rel_type": "org.example.relationship",
+    "event_id": "$an_event"
+  }
+}
+properties:
+  rel_type:
+    type: string
+    description: |-
+      The namespaced relationship type. Values must use the
+      [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
+
+      The relationship type determines how clients should perceive the event, and in what
+      context. Some relationship types are processed server-side for "bundling", though not
+      all relationships require such behaviour. For example, an [`m.thread` relationship type](/client-server-api/#threading)
+      denotes that the event is part of a "thread" of messages and should be rendered as
+      such.
+  event_id:
+    type: string
+    format: mx-event-id
+    pattern: "^\\$"
+    description: The event ID of the event that this event relates to.
+required: ['rel_type', 'event_id']

data/data/matrix-spec/api/client-server/definitions/megolm_export_session_data.yaml

@@ -0,0 +1,39 @@
+# 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.
+
+
+allOf:
+  - $ref: key_backup_session_data.yaml
+  - type: object
+    title: ExportedSessionData
+    description: |-
+      The format used to encode a Megolm session key for export.
+
+      This is similar to the format before encryption used for the session keys
+      in [Server-side key backups](/client-server-api/#server-side-key-backups)
+      but adds the `room_id` and `session_id` fields.
+    properties:
+      room_id:
+        type: string
+        description: |-
+          The room where the session is used.
+        example: "!Cuyf34gef24t:localhost"
+      session_id:
+        type: string
+        description: |-
+          The Megolm session ID.
+        example: "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ"
+    required:
+      - room_id
+      - session_id

data/data/matrix-spec/api/client-server/definitions/olm_payload.yaml

@@ -0,0 +1,88 @@
+# Copyright 2025 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.
+
+
+type: object
+title: OlmPayload
+description: |-
+  The plaintext payload of Olm message events.
+properties:
+  type:
+    type: string
+    description: The type of the event.
+  content:
+    type: object
+    description: The event content.
+  sender:
+    type: string
+    description: The user ID of the event sender.
+  recipient:
+    type: string
+    description: The user ID of the intended event recipient.
+  recipient_keys:
+    description: The recipient's signing keys of the encrypted event.
+    $ref: "#/components/schemas/SigningKeys"
+  keys:
+    $ref: "#/components/schemas/SigningKeys"
+    description: The sender's signing keys of the encrypted event.
+  sender_device_keys:
+    $ref: device_keys.yaml 
+    description: The sender's device keys.
+    x-addedInMatrixVersion: "1.15"
+required:
+  - type
+  - content
+  - sender
+  - recipient
+  - recipient_keys
+  - keys
+components:
+  schemas:
+    SigningKeys:
+      type: object
+      title: SigningKeys
+      description: Public keys used for an `m.olm.v1.curve25519-aes-sha2` event.
+      properties:
+        ed25519:
+          type: string
+          description: The Ed25519 public key encoded using unpadded base64.
+      required:
+        - ed25519
+example: {
+  "type": "<type of the plaintext event>",
+  "content": "<content for the plaintext event>",
+  "sender": "<sender_user_id>",
+  "recipient": "<recipient_user_id>",
+  "recipient_keys": {
+    "ed25519": "<our_ed25519_key>"
+  },
+  "keys": {
+    "ed25519": "<sender_ed25519_key>"
+  },
+  "sender_device_keys": {
+    "algorithms": ["<supported>", "<algorithms>"],
+    "user_id": "<user_id>",
+    "device_id": "<device_id>",
+    "keys": {
+      "ed25519:<device_id>": "<sender_ed25519_key>",
+      "curve25519:<device_id>": "<sender_curve25519_key>"
+    },
+    "signatures": {
+      "<user_id>": {
+        "ed25519:<device_id>": "<device_signature>",
+        "ed25519:<ssk_id>": "<ssk_signature>",
+      }
+    }
+  }
+}

data/data/matrix-spec/api/client-server/definitions/one_time_keys.yaml

@@ -0,0 +1,27 @@
+---
+title: OneTimeKeys
+type: object
+description: |-
+  One-time public keys.  The names of the properties should be in the format
+  `<algorithm>:<key_id>`. The format of the key is determined
+  by the [key algorithm](/client-server-api/#key-algorithms).
+additionalProperties:
+  oneOf:
+    - type: string
+    - type: object
+      title: KeyObject
+      properties:
+        key:
+          type: string
+          description: The key, encoded using unpadded base64.
+        signatures:
+          type: object
+          description: |-
+            Signature for the device. Mapped from user ID to signature object,
+            containing mapping from _key signing identifier_ to the signature
+            (see also: [Signing JSON](/appendices/#signing-json))
+          patternProperties:
+            "^@":
+              x-pattern-format: mx-user-id
+              type: object
+      required: ['key', 'signatures']

data/data/matrix-spec/api/client-server/definitions/openid_token.yaml

@@ -0,0 +1,37 @@
+# Copyright 2018 New Vector Ltd
+# Copyright 2019 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.
+type: object
+title: OpenIdCredentials
+properties:
+  access_token:
+    type: string
+    description: |-
+      An access token the consumer may use to verify the identity of
+      the person who generated the token. This is given to the federation
+      API `GET /openid/userinfo` to verify the user's identity.
+  token_type:
+    type: string
+    description: The string `Bearer`.
+  matrix_server_name:
+    type: string
+    description: |-
+      The homeserver domain the consumer should use when attempting to
+      verify the user's identity.
+  expires_in:
+    type: integer
+    description: |-
+      The number of seconds before this token expires and a new one must
+      be generated.
+required: ['access_token', 'token_type', 'matrix_server_name', 'expires_in']

data/data/matrix-spec/api/client-server/definitions/protocol.yaml

@@ -0,0 +1,44 @@
+# 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.
+allOf:
+- $ref: ../../application-service/definitions/protocol_base.yaml
+- type: object
+  properties:
+    instances:
+      description: |-
+        A list of objects representing independent instances of configuration.
+        For example, multiple networks on IRC if multiple are provided by the
+        same application service.
+
+        The instances are modified by the homeserver from the response of
+        [`GET /_matrix/app/v1/thirdparty/protocol/{protocol}`](/application-service-api/#get_matrixappv1thirdpartyprotocolprotocol)
+        to include an `instance_id` to serve as a unique identifier for each
+        instance on the homeserver.
+      type: array
+      items:
+        allOf:
+          - $ref: ../../application-service/definitions/protocol_instance.yaml
+          - type: object
+            properties:
+              instance_id:
+                type: string
+                description: |-
+                  A unique identifier for this instance on the homeserver. This field is added
+                  to the response of [`GET /_matrix/app/v1/thirdparty/protocol/{protocol}`](/application-service-api/#get_matrixappv1thirdpartyprotocolprotocol)
+                  by the homeserver.
+
+                  This is the identifier to use as the `third_party_instance_id` in a request to
+                  [`POST /_matrix/client/v3/publicRooms`](/client-server-api/#post_matrixclientv3publicrooms).
+                example: "irc-freenode"
+  required: ['instances']

data/data/matrix-spec/api/client-server/definitions/public_rooms_chunk.yaml

@@ -0,0 +1,74 @@
+# Copyright 2021 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.
+
+type: object
+title: "PublishedRoomsChunk"
+properties:
+  canonical_alias:
+    type: string
+    format: mx-room-alias
+    pattern: "^#"
+    description: The canonical alias of the room, if any.
+    example: "#general:example.org"
+  name:
+    type: string
+    description: The name of the room, if any.
+    example: "General Chat"
+  num_joined_members:
+    type: integer
+    description: The number of members joined to the room.
+    example: 42
+  room_id:
+    type: string
+    format: mx-room-id
+    pattern: "^!"
+    description: The ID of the room.
+    example: "!abcdefg:example.org"
+  topic:
+    type: string
+    description: |-
+      The plain text topic of the room. Omitted if no `text/plain` mimetype
+      exists in [`m.room.topic`](/client-server-api/#mroomtopic).
+    example: "All things general"
+  world_readable:
+    type: boolean
+    description: Whether the room may be viewed by users without joining.
+    example: false
+  guest_can_join:
+    type: boolean
+    description: |-
+      Whether guest users may join the room and participate in it.
+      If they can, they will be subject to ordinary power level
+      rules like any other user.
+    example: true
+  avatar_url:
+    type: string
+    format: uri
+    description: The URL for the room's avatar, if one is set.
+    example: "mxc://example.org/abcdef"
+  join_rule:
+    type: string
+    description: |-
+      The room's join rule. When not present, the room is assumed to
+      be `public`.
+    example: "public"
+  room_type:
+    type: string
+    description: |-
+      The `type` of room (from [`m.room.create`](/client-server-api/#mroomcreate)), if any.
+required:
+  - room_id
+  - num_joined_members
+  - world_readable
+  - guest_can_join

data/data/matrix-spec/api/client-server/definitions/public_rooms_response.yaml

@@ -0,0 +1,59 @@
+# Copyright 2018, 2021 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.
+
+type: object
+description: A list of the published rooms on the server.
+required: ["chunk"]
+properties:
+  chunk:
+    type: array
+    description: |-
+      A paginated chunk of published rooms.
+    items:
+      $ref: "public_rooms_chunk.yaml"
+  next_batch:
+    type: string
+    description: |-
+      A pagination token for the response. The absence of this token
+      means there are no more results to fetch and the client should
+      stop paginating.
+  prev_batch:
+    type: string
+    description: |-
+      A pagination token that allows fetching previous results. The
+      absence of this token means there are no results before this
+      batch, i.e. this is the first batch.
+  total_room_count_estimate:
+    type: integer
+    description: |-
+        An estimate on the total number of published rooms, if the
+        server has an estimate.
+example: {
+  "chunk": [
+    {
+      "avatar_url": "mxc://bleecker.street/CHEDDARandBRIE",
+      "guest_can_join": false,
+      "name": "CHEESE",
+      "num_joined_members": 37,
+      "room_id": "!ol19s:bleecker.street",
+      "topic": "Tasty tasty cheese",
+      "world_readable": true,
+      "join_rule": "public",
+      "room_type": "m.space"
+    }
+  ],
+  "next_batch": "p190q",
+  "prev_batch": "p1902",
+  "total_room_count_estimate": 115
+}