async-matrix 0.1.3 → 1.1.0

data/data/matrix-spec/event-schemas/schema/core-event-schema/sync_room_event.yaml

@@ -0,0 +1,49 @@
+# 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.
+
+# Note: this is technically not a core event schema, however it is included here
+# to keep things sane. The short story is that /sync doesn't require a room_id to
+# be on events, so we give it a whole event structure as a base for room_event.
+# This base doesn't declare a room_id, which instead appears in the room_event.
+
+$schema: https://json-schema.org/draft/2020-12/schema
+
+title: SyncRoomEvent
+description: In addition to the Event fields, Room Events have the following additional
+  fields.
+allOf:
+- $ref: event.yaml
+- type: object
+  properties:
+    event_id:
+      description: The globally unique event identifier.
+      type: string
+      format: mx-event-id
+      pattern: "^\\$"
+    sender:
+      description: Contains the fully-qualified ID of the user who sent this event.
+      type: string
+      format: mx-user-id
+      pattern: "^@"
+    origin_server_ts:
+      description: Timestamp in milliseconds on originating homeserver
+        when this event was sent.
+      type: integer
+      format: int64
+    unsigned:
+      $ref: unsigned_prop.yaml
+  required:
+  - event_id
+  - sender
+  - origin_server_ts

data/data/matrix-spec/event-schemas/schema/core-event-schema/sync_state_event.yaml

@@ -0,0 +1,36 @@
+# 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.
+
+# See sync_room_event.yaml for why this file is here.
+
+$schema: https://json-schema.org/draft/2020-12/schema
+
+title: SyncStateEvent
+description: In addition to the Room Event fields, State Events have the following
+  additional fields.
+allOf:
+- $ref: sync_room_event.yaml
+- type: object
+  properties:
+    state_key:
+      description: A unique key which defines the overwriting semantics for this piece
+        of room state. This value is often a zero-length string. The presence of this
+        key makes this event a State Event.
+
+        State keys starting with an `@` are reserved for referencing user IDs, such
+        as room members. With the exception of a few events, state events set with a
+        given user's ID as the state key MUST only be set by that user.
+      type: string
+  required:
+  - state_key

data/data/matrix-spec/event-schemas/schema/core-event-schema/unsigned_prop.yaml

@@ -0,0 +1,23 @@
+# Copyright 2020 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+$schema: https://json-schema.org/draft/2020-12/schema
+
+title: UnsignedData
+type: object
+description: Contains optional extra information about the event.
+properties:
+  age:
+    description: The time in milliseconds that has elapsed since the event was
+      sent.
+    type: integer

data/data/matrix-spec/event-schemas/schema/m.accepted_terms.yaml

@@ -0,0 +1,25 @@
+---
+$schema: https://json-schema.org/draft/2020-12/schema
+
+allOf:
+  - $ref: core-event-schema/event.yaml
+description: |-
+  A list of terms URLs the user has previously accepted. Clients SHOULD use this
+  to avoid presenting the user with terms they have already agreed to.
+properties:
+  content:
+    type: object
+    properties:
+      accepted:
+        type: array
+        items:
+          type: string
+        description: |-
+          The list of URLs the user has previously accepted. Should be appended to
+          when the user agrees to new terms.
+  type:
+    enum:
+      - m.accepted_terms
+    type: string
+title: Accepted Terms of Service URLs
+type: object

data/data/matrix-spec/event-schemas/schema/m.call.answer.yaml

@@ -0,0 +1,44 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "description": "This event is sent by the callee when they wish to answer the call.",
+    "x-weight": 40,
+    "allOf": [{
+        "$ref": "core-event-schema/room_event.yaml"
+    }],
+    "properties": {
+        "content": {
+            "type": "object",
+            "allOf": [{
+                "$ref": "core-event-schema/call_event.yaml"
+            }],
+            "properties": {
+                "answer": {
+                    "type": "object",
+                    "title": "Answer",
+                    "description": "The session description object",
+                    "properties": {
+                        "type": {
+                            "type": "string",
+                            "enum": ["answer"],
+                            "description": "The type of session description."
+                        },
+                        "sdp": {
+                            "type": "string",
+                            "description": "The SDP text of the session description."
+                        }
+                    },
+                    "required": ["type", "sdp"]
+                },
+                "sdp_stream_metadata": {
+                    "$ref": "components/sdp_stream_metadata.yaml"
+                }
+            },
+            "required": ["answer"]
+        },
+        "type": {
+            "type": "string",
+            "enum": ["m.call.answer"]
+        }
+    }
+}

data/data/matrix-spec/event-schemas/schema/m.call.candidates.yaml

@@ -0,0 +1,52 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+
+type: object
+description: |-
+  This event is sent by callers after sending an invite and by the callee after
+  answering. Its purpose is to give the other party additional ICE candidates to
+  try using to communicate.
+x-weight: 20
+allOf:
+  - $ref: core-event-schema/room_event.yaml
+properties:
+  content:
+    type: object
+    allOf:
+      - $ref: core-event-schema/call_event.yaml
+    properties:
+      candidates:
+        type: array
+        description: Array of objects describing the candidates.
+        items:
+          type: object
+          title: Candidate
+          properties:
+            sdpMid:
+              type: string
+              description: |-
+                The SDP media type this candidate is intended for.
+
+                At least one of `sdpMid` or `sdpMLineIndex` is required, unless
+                this an end-of-candidates candidate.
+            sdpMLineIndex:
+              type: number
+              description: |-
+                The index of the SDP 'm' line this candidate is intended for.
+
+                At least one of `sdpMid` or `sdpMLineIndex` is required, unless
+                this an end-of-candidates candidate.
+            candidate:
+              type: string
+              description: |-
+                The SDP 'a' line of the candidate.
+
+                If this is an [end-of-candidates](/client-server-api/#end-of-candidates)
+                candidate, this is the empty string.
+          required:
+            - candidate
+    required:
+      - candidates
+  type:
+    type: string
+    enum:
+      - m.call.candidates

data/data/matrix-spec/event-schemas/schema/m.call.hangup.yaml

@@ -0,0 +1,57 @@
+---
+$schema: https://json-schema.org/draft/2020-12/schema
+
+type: object
+description: |
+  Sent by either party to signal their termination of the call. This can
+  be sent either once the call has has been established or before to abort the call.
+
+  The meanings of the `reason` field are as follows:
+   * `ice_failed`: ICE negotiation has failed and a media connection could not be established.
+   * `ice_timeout`: The connection failed after some media was exchanged (as opposed to `ice_failed`
+      which means no media connection could be established). Note that, in the case of an ICE
+      renegotiation, a client should be sure to send `ice_timeout` rather than `ice_failed` if media
+      had previously been received successfully, even if the ICE renegotiation itself failed.
+   * `invite_timeout`: The other party did not answer in time.
+   * `user_hangup`: Clients must now send this code when the user chooses to end the call, although
+     for backwards compatibility with version 0, a clients should treat an absence of the `reason`
+     field as `user_hangup`.
+   * `user_media_failed`: The client was unable to start capturing media in such a way that it is unable
+     to continue the call.
+   * `user_busy`: The user is busy. Note that this exists primarily for bridging to other networks such
+      as the PSTN. A Matrix client that receives a call whilst already in a call would not generally reject
+      the new call unless the user had specifically chosen to do so.
+   * `unknown_error`: Some other failure occurred that meant the client was unable to continue the call
+      rather than the user choosing to end it.
+x-weight: 80
+allOf:
+- "$ref": core-event-schema/room_event.yaml
+properties:
+  content:
+    type: object
+    allOf:
+    - "$ref": core-event-schema/call_event.yaml
+    properties:
+      reason:
+        type: string
+        description: Reason for the hangup. Note that this was optional in
+          previous previous versions of the spec, so a missing value should be
+          treated as `user_hangup`.
+        x-changedInMatrixVersion:
+          "1.7": |-
+            Additional values were added.
+        enum:
+        - ice_timeout
+        - ice_failed
+        - invite_timeout
+        - user_hangup
+        - user_media_failed
+        - user_busy
+        - unknown_error
+    required:
+    - reason
+  type:
+    type: string
+    enum:
+    - m.call.hangup
+

data/data/matrix-spec/event-schemas/schema/m.call.invite.yaml

@@ -0,0 +1,53 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "description": "This event is sent by the caller when they wish to establish a call.",
+    "x-weight": 10,
+    "allOf": [{
+        "$ref": "core-event-schema/room_event.yaml"
+    }],
+    "properties": {
+        "content": {
+            "type": "object",
+            "allOf": [{
+                "$ref": "core-event-schema/call_event.yaml"
+            }],
+            "properties": {
+                "offer": {
+                    "type": "object",
+                    "title": "Offer",
+                    "description": "The session description object",
+                    "properties": {
+                        "type": {
+                            "type": "string",
+                            "enum": ["offer"],
+                            "description": "The type of session description."
+                        },
+                        "sdp": {
+                            "type": "string",
+                            "description": "The SDP text of the session description."
+                        }
+                    },
+                    "required": ["type", "sdp"]
+                },
+                "lifetime": {
+                    "type": "integer",
+                    "description": "The time in milliseconds that the invite is valid for. Once the invite age exceeds this value, clients should discard it. They should also no longer show the call as awaiting an answer in the UI."
+                },
+                "invitee": {
+                    "type": "string",
+                    "description": "The ID of the user being called. If omitted, any user in the room can answer.",
+                    "x-addedInMatrixVersion": "1.7"
+                },
+                "sdp_stream_metadata": {
+                    "$ref": "components/sdp_stream_metadata.yaml"
+                }
+            },
+            "required": ["offer", "lifetime"]
+        },
+        "type": {
+            "type": "string",
+            "enum": ["m.call.invite"]
+        }
+    }
+}

data/data/matrix-spec/event-schemas/schema/m.call.negotiate.yaml

@@ -0,0 +1,78 @@
+---
+$schema: https://json-schema.org/draft/2020-12/schema
+
+type: object
+description: |
+  Provides SDP negotiation semantics for media pause, hold/resume, ICE restarts
+  and voice/video call up/downgrading. Clients should implement and honour hold
+  functionality as per [WebRTC's recommendation](https://www.w3.org/TR/webrtc/#hold-functionality).
+
+  If both the invite event and the accepted answer event have `version` equal
+  to `"1"`, either party may send `m.call.negotiate` with a `description` field
+  to offer new SDP to the other party. This event has `call_id` with the ID of
+  the call and `party_id` equal to the client's party ID for that call.  The
+  caller ignores any negotiate events with `party_id` + `user_id` tuple not
+  equal to that of the answer it accepted and the callee ignores any negotiate
+  events with `party_id` + `user_id` tuple not equal to that of the caller.
+  Clients should use the `party_id` field to ignore the remote echo of their
+  own negotiate events.
+
+  This has a `lifetime` field as in `m.call.invite`, after which the sender of
+  the negotiate event should consider the negotiation failed (timed out) and
+  the recipient should ignore it.
+
+  The `description` field is the same as the `offer` field in `m.call.invite`
+  and `answer` field in `m.call.answer` and is an `RTCSessionDescriptionInit`
+  object as per https://www.w3.org/TR/webrtc/#dom-rtcsessiondescriptioninit.
+
+  Once an `m.call.negotiate` event is received, the client must respond with
+  another `m.call.negotiate` event, with the SDP answer (with `"type": "answer"`)
+  in the `description` property.
+
+  In the `m.call.invite` and `m.call.answer` events, the `offer` and `answer`
+  fields respectively are objects of type `RTCSessionDescriptionInit`.  Hence
+  the `type` field, whilst redundant in these events, is included for ease of
+  working with the WebRTC API and is mandatory. Receiving clients should not
+  attempt to validate the `type` field, but simply pass the object into the
+  WebRTC API.
+x-addedInMatrixVersion: "1.7"
+x-weight: 60
+allOf:
+- "$ref": core-event-schema/room_event.yaml
+properties:
+  content:
+    type: object
+    allOf:
+    - "$ref": core-event-schema/call_event.yaml
+    properties:
+      description:
+        type: object
+        title: Description
+        description: The session description object
+        properties:
+          type:
+            type: string
+            enum:
+            - offer
+            - answer
+            description: The type of session description.
+          sdp:
+            type: string
+            description: The SDP text of the session description.
+        required:
+        - type
+        - sdp
+      lifetime:
+        type: integer
+        description: The time in milliseconds that the negotiation is valid for.
+          Once the negotiation age exceeds this value, clients should discard it.
+      sdp_stream_metadata:
+        $ref: components/sdp_stream_metadata.yaml
+    required:
+    - description
+    - lifetime
+  type:
+    type: string
+    enum:
+    - m.call.negotiate
+

data/data/matrix-spec/event-schemas/schema/m.call.reject.yaml

@@ -0,0 +1,29 @@
+---
+$schema: https://json-schema.org/draft/2020-12/schema
+
+type: object
+description: |
+  If the `m.call.invite` event has `version` `"1"`, a client wishing to
+  reject the call sends an `m.call.reject` event. This rejects the call on all devices,
+  but if the calling device sees an `answer` before the `reject`, it disregards the
+  reject event and carries on. The reject has a `party_id` just like an answer, and
+  the caller sends a `select_answer` for it just like an answer. If another client
+  had already sent an answer and sees the caller select the reject response instead
+  of its answer, it ends the call. If the `m.call.invite` event has `version` `0`,
+  the callee sends an `m.call.hangup` event. If the calling user chooses to end the
+  call before setup is complete, the client sends `m.call.hangup` as previously.
+
+  Note that, unlike `m.call.hangup`, this event has no `reason` field: the rejection of
+  a call is always implicitly because the user chose not to answer it.
+x-addedInMatrixVersion: "1.7"
+x-weight: 30
+allOf:
+- "$ref": core-event-schema/room_event.yaml
+properties:
+  content:
+    "$ref": core-event-schema/call_event.yaml
+  type:
+    type: string
+    enum:
+    - m.call.reject
+

data/data/matrix-spec/event-schemas/schema/m.call.sdp_stream_metadata_changed.yaml

@@ -0,0 +1,24 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+
+type: object
+x-addedInMatrixVersion: "1.11"
+x-weight: 70
+description: |-
+  This event is sent by callers when they wish to update a stream's metadata
+  but no negotiation is required.
+allOf:
+  - $ref: core-event-schema/room_event.yaml
+properties:
+  content:
+    type: object
+    allOf:
+    - $ref: core-event-schema/call_event.yaml
+    properties:
+      sdp_stream_metadata:
+        $ref: components/sdp_stream_metadata.yaml
+    required:
+    - sdp_stream_metadata
+  type:
+    type: string
+    enum:
+    - m.call.sdp_stream_metadata_changed

data/data/matrix-spec/event-schemas/schema/m.call.select_answer.yaml

@@ -0,0 +1,29 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "description": "This event is sent by the caller's client once it has decided which other client to talk to, by selecting one of multiple possible incoming `m.call.answer` events. Its `selected_party_id` field indicates the answer it's chosen. The `call_id` and `party_id` of the caller is also included. If the callee's client sees a `select_answer` for an answer with party ID other than the one it sent, it ends the call and informs the user the call was answered elsewhere. It does not send any events. Media can start flowing before this event is seen or even sent.  Clients that implement previous versions of this specification will ignore this event and behave as they did before.",
+    "x-addedInMatrixVersion": "1.7",
+    "x-weight": 50,
+    "allOf": [{
+        "$ref": "core-event-schema/room_event.yaml"
+    }],
+    "properties": {
+        "content": {
+            "type": "object",
+            "allOf": [{
+                "$ref": "core-event-schema/call_event.yaml"
+            }],
+            "properties": {
+                "selected_party_id": {
+                    "type": "string",
+                    "description": "The `party_id` field from the answer event that the caller chose."
+                },
+            },
+            "required": ["selected_party_id"]
+        },
+        "type": {
+            "type": "string",
+            "enum": ["m.call.select_answer"]
+        }
+    }
+}

data/data/matrix-spec/event-schemas/schema/m.direct.yaml

@@ -0,0 +1,29 @@
+---
+$schema: https://json-schema.org/draft/2020-12/schema
+
+allOf:
+  - $ref: core-event-schema/event.yaml
+description: |-
+  A map of which rooms are considered 'direct' rooms for specific users
+  is kept in  `account_data` in an event of type `m.direct`. The
+  content of this event is an object where the keys are the user IDs
+  and values are lists of room ID strings of the 'direct' rooms for
+  that user ID.
+properties:
+  content:
+    patternProperties:
+      "^@":
+        x-pattern-format: mx-user-id
+        type: array
+        items:
+          type: string
+    type: object
+    description: |-
+      The mapping of user ID to a list of room IDs of the 'direct' rooms for
+      that user ID.
+  type:
+    enum:
+      - m.direct
+    type: string
+title: Direct Chat Mapping
+type: object

data/data/matrix-spec/event-schemas/schema/m.dummy.yaml

@@ -0,0 +1,25 @@
+---
+$schema: https://json-schema.org/draft/2020-12/schema
+
+allOf:
+  - $ref: core-event-schema/event.yaml
+
+description: |-
+  This event type is used to indicate new Olm sessions for end-to-end encryption.
+  Typically it is encrypted as an `m.room.encrypted` event, then sent as a [to-device](/client-server-api/#send-to-device-messaging)
+  event.
+
+  The event does not have any content associated with it. The sending client is expected
+  to send a key share request shortly after this message, causing the receiving client to
+  process this `m.dummy` event as the most recent event and using the keyshare request
+  to set up the session. The keyshare request and `m.dummy` combination should result
+  in the original sending client receiving keys over the newly established session.
+properties:
+  content:
+    properties: {}
+    type: object
+  type:
+    enum:
+      - m.dummy
+    type: string
+type: object

data/data/matrix-spec/event-schemas/schema/m.forwarded_room_key.yaml

@@ -0,0 +1,70 @@
+---
+$schema: https://json-schema.org/draft/2020-12/schema
+
+allOf:
+  - $ref: core-event-schema/event.yaml
+
+description: |-
+  This event type is used to forward keys for end-to-end encryption.
+  It is encrypted as an `m.room.encrypted` event using [Olm](/client-server-api/#molmv1curve25519-aes-sha2),
+  then sent as a [to-device](/client-server-api/#send-to-device-messaging) event.
+properties:
+  content:
+    properties:
+      algorithm:
+        type: string
+        description: |-
+          The encryption algorithm the key in this event is to be used with.
+      room_id:
+        type: string
+        description: The room where the key is used.
+      sender_key:
+        type: string
+        description: |-
+          The Curve25519 key of the device which initiated the session originally.
+      session_id:
+        type: string
+        description: The ID of the session that the key is for.
+      session_key:
+        type: string
+        description: The key to be exchanged.
+      sender_claimed_ed25519_key:
+        type: string
+        description: |-
+          The Ed25519 key of the device which initiated the session originally.
+          It is 'claimed' because the receiving device has no way to tell that the
+          original room_key actually came from a device which owns the private part of
+          this key unless they have done device verification.
+      forwarding_curve25519_key_chain:
+        type: array
+        items:
+          type: string
+        description: |-
+          Chain of Curve25519 keys. It starts out empty, but each time the
+          key is forwarded to another device, the previous sender in the chain is added
+          to the end of the list. For example, if the key is forwarded from A to B to
+          C, this field is empty between A and B, and contains A's Curve25519 key between
+          B and C.
+      withheld:
+        type: object
+        description: |-
+          Indicates that the key cannot be used to decrypt all the messages
+          from the session because a portion of the session was withheld as
+          described in [Reporting that decryption keys are withheld](/client-server-api/#reporting-that-decryption-keys-are-withheld). This
+          object must include the `code` and `reason` properties from the
+          `m.room_key.withheld` message that was received by the sender of
+          this message.
+    required:
+      - algorithm
+      - room_id
+      - session_id
+      - session_key
+      - sender_claimed_ed25519_key
+      - forwarding_curve25519_key_chain
+      - sender_key
+    type: object
+  type:
+    enum:
+      - m.forwarded_room_key
+    type: string
+type: object

data/data/matrix-spec/event-schemas/schema/m.fully_read.yaml

@@ -0,0 +1,26 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "title": "Read Marker Location Event",
+    "description": "The current location of the user's read marker in a room. This event appears in the user's room account data for the room the marker is applicable for.",
+    "allOf": [{
+        "$ref": "core-event-schema/event.yaml"
+    }],
+    "properties": {
+        "content": {
+            "type": "object",
+            "properties": {
+                "event_id": {
+                    "type": "string",
+                    "description": "The event the user's read marker is located at in the room."
+                }
+            },
+            "required": ["event_id"]
+        },
+        "type": {
+            "type": "string",
+            "enum": ["m.fully_read"]
+        }
+    },
+    "required": ["type", "content"]
+}