mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-03-26 13:04:10 +01:00
Merge remote-tracking branch 'origin/main' into rav/clarify_aggregations
This commit is contained in:
Richard van der Hoff
commit
24ae7cd403
|
|
@ -167,3 +167,15 @@ include the line in your commit or pull request comment::
|
|||
can't be accepted. Git makes this trivial - just use the -s flag when you do
|
||||
``git commit``, having first set ``user.name`` and ``user.email`` git configs
|
||||
(which you should have done anyway :)
|
||||
|
||||
Private sign off
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
If you would like to provide your legal name privately to the Matrix.org
|
||||
Foundation (instead of in a public commit or comment), you can do so by emailing
|
||||
your legal name and a link to the pull request to dco@matrix.org. It helps to
|
||||
include "sign off" or similar in the subject line. You will then be instructed
|
||||
further.
|
||||
|
||||
Once private sign off is complete, doing so for future contributions will not
|
||||
be required.
|
||||
|
|
|
|||
|
|
@ -41,12 +41,12 @@ $table-row-default: $secondary-lighter-background;
|
|||
$td-enable-google-fonts: false;
|
||||
|
||||
/*
|
||||
* Replace the default font with Inter - we load it from a local copy, which is downloaded from
|
||||
* Google Fonts manually via a script:
|
||||
* https://github.com/matrix-org/matrix-spec/tree/main/static/css/fonts
|
||||
* Replace the default font with Inter.
|
||||
*
|
||||
* The $font-family-sans-serif definition here overrides the default value set by docsy:
|
||||
* https://github.com/matrix-org/docsy/blob/66a4e61d2d34edc7196b9df83a7d09cd4af14b47/assets/scss/_variables.scss#L68
|
||||
* and adds "Inter" to the front. */
|
||||
@import url("../css/fonts/Inter.css");
|
||||
$font-family-sans-serif: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
|
||||
* and adds "Inter" to the front.
|
||||
*
|
||||
* The font itself is loaded via stylesheet link layouts/partials/hooks/head-end.html.
|
||||
*/
|
||||
$font-family-sans-serif: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
|
||||
|
|
|
|||
|
|
@ -288,16 +288,20 @@ footer {
|
|||
/* Styles for sections that are rendered from data, such as HTTP APIs and event schemas */
|
||||
.rendered-data {
|
||||
background-color: $secondary-lightest-background;
|
||||
padding: 1rem;
|
||||
margin: 1rem 0;
|
||||
padding: 0.85rem;
|
||||
margin: 0.85rem 0;
|
||||
|
||||
details {
|
||||
summary {
|
||||
padding: .5rem 0;
|
||||
p {
|
||||
max-width: 80%;
|
||||
h1 {
|
||||
margin: 0;
|
||||
/* Ensure the disclosure control is vertically centred with the header text. */
|
||||
vertical-align: middle;
|
||||
}
|
||||
}
|
||||
p {
|
||||
max-width: 80%;
|
||||
}
|
||||
}
|
||||
|
||||
.deprecated-inline {
|
||||
|
|
|
|||
|
|
@ -246,7 +246,7 @@ anyway.
|
|||
In this arrangement there is now a room with both users may join but neither has
|
||||
the power to invite any others. Both users now have the confidence that (at
|
||||
least within the messaging system itself) their messages remain private and
|
||||
cannot later be provably leaked to a third party. They can freely set the topic
|
||||
cannot later be provably leaked to a third-party. They can freely set the topic
|
||||
or name if they choose and add or edit any other state of the room. The update
|
||||
powerlevel of each of these fixed properties should be 1, to lock out the users
|
||||
from being able to alter them.
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
======================
|
||||
Third Party Identities
|
||||
Third-party Identities
|
||||
======================
|
||||
|
||||
A description of how email addresses, mobile phone numbers and other third
|
||||
party identifiers can be used to authenticate and discover users in Matrix.
|
||||
A description of how email addresses, mobile phone numbers and other third-party
|
||||
identifiers can be used to authenticate and discover users in Matrix.
|
||||
|
||||
|
||||
Overview
|
||||
|
|
@ -15,16 +15,16 @@ and phone numbers for contacts in their address book. They want to communicate
|
|||
with those contacts in Matrix without manually exchanging a Matrix User ID with
|
||||
them.
|
||||
|
||||
Third Party IDs
|
||||
Third-party IDs
|
||||
---------------
|
||||
|
||||
[[TODO(markjh): Describe the format of a 3PID]]
|
||||
|
||||
|
||||
Third Party ID Associations
|
||||
Third-party ID Associations
|
||||
---------------------------
|
||||
|
||||
An Associaton is a binding between a Matrix User ID and a Third Party ID (3PID).
|
||||
An Associaton is a binding between a Matrix User ID and a Third-party ID (3PID).
|
||||
Each 3PID can be associated with one Matrix User ID at a time.
|
||||
|
||||
[[TODO(markjh): JSON format of the association.]]
|
||||
|
|
|
|||
1
changelogs/appendices/newsfragments/1468.clarification
Normal file
1
changelogs/appendices/newsfragments/1468.clarification
Normal file
|
|
@ -0,0 +1 @@
|
|||
Clarify that the term "Canonical JSON" is a specific thing within the matrix specification.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add information on standard error responses for unknown endpoints/methods.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Fix various typos throughout the specification.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify the power levels integer range.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify that `/context` always returns `event` even if `limit` is zero. Contributed by @sumnerevans at @beeper.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify what fields are required when deleting a pusher
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add information on standard error responses for unknown endpoints/methods.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Improve the presentation of push rule kinds and actions.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add missing description to m.call.answer schema.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify the power levels integer range.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add `/rooms/<roomID>/timestamp_to_event` endpoint, as per [MSC3030](https://github.com/matrix-org/matrix-spec-proposals/pull/3030).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify parts of the end-to-end encryption sections.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Move login API definitions to the right heading. Contributed by @HarHarLinks.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add links to the spec for the definition of 3PID `medium`.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Fix various typos throughout the specification.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Clarify that reply chain fallback for threads may not be present.
|
||||
1
changelogs/client_server/newsfragments/1440.feature
Normal file
1
changelogs/client_server/newsfragments/1440.feature
Normal file
|
|
@ -0,0 +1 @@
|
|||
Changes to the server-side aggregation of `m.replace` (edit) events, as per [MSC3925](https://github.com/matrix-org/matrix-spec-proposals/pull/3925).
|
||||
|
|
@ -0,0 +1 @@
|
|||
Clarify what event property the content-specific push rules match against.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Fix various typos throughout the specification.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Clarify the semantics that make requests idempotent.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Fix various typos throughout the specification.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Improve documentation of how clients use push rules.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Clarify that servers should enforce a default `limit` on a filter if one is not specified.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Fix various typos throughout the specification.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add information on standard error responses for unknown endpoints/methods.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add link to the unstable spec to the README.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Improve safety of the proposals retrieval script in the event of failure.
|
||||
|
|
@ -1,2 +0,0 @@
|
|||
Rename "<content>" to "content" in the OpenAPI files for content uploads.
|
||||
|
||||
|
|
@ -1 +0,0 @@
|
|||
Stop autogenerating examples where we already have an example.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Improve formatting of definitions in the Push Notifications section.
|
||||
1
changelogs/internal/newsfragments/1444.clarification
Normal file
1
changelogs/internal/newsfragments/1444.clarification
Normal file
|
|
@ -0,0 +1 @@
|
|||
Update references to Inter font.
|
||||
1
changelogs/internal/newsfragments/1446.clarification
Normal file
1
changelogs/internal/newsfragments/1446.clarification
Normal file
|
|
@ -0,0 +1 @@
|
|||
Endpoint disclosures now hide everything but the URL.
|
||||
|
|
@ -22,5 +22,5 @@ r0.1.0
|
|||
|
||||
This is the first release of the Application Service specification. It
|
||||
includes support for application services being able to interact with
|
||||
homeservers and bridge third party networks, such as IRC, over to Matrix
|
||||
homeservers and bridge third-party networks, such as IRC, over to Matrix
|
||||
in a standard and accessible way.
|
||||
|
|
|
|||
|
|
@ -211,7 +211,7 @@ Backwards Compatible Changes
|
|||
- Add a common standard for user, room, and group mentions in messages. (`#1547 <https://github.com/matrix-org/matrix-doc/issues/1547>`_)
|
||||
- Add server ACLs as an option for controlling federation in a room. (`#1550 <https://github.com/matrix-org/matrix-doc/issues/1550>`_)
|
||||
- Add new push rules for encrypted events and ``@room`` notifications. (`#1551 <https://github.com/matrix-org/matrix-doc/issues/1551>`_)
|
||||
- Add third party network room directories, as provided by application services. (`#1554 <https://github.com/matrix-org/matrix-doc/issues/1554>`_)
|
||||
- Add third-party network room directories, as provided by application services. (`#1554 <https://github.com/matrix-org/matrix-doc/issues/1554>`_)
|
||||
- Document the ``validated_at`` and ``added_at`` fields on ``GET /acount/3pid``. (`#1567 <https://github.com/matrix-org/matrix-doc/issues/1567>`_)
|
||||
- Add an ``inhibit_login`` registration option. (`#1589 <https://github.com/matrix-org/matrix-doc/issues/1589>`_)
|
||||
- Recommend that servers set a Content Security Policy for the content repository. (`#1600 <https://github.com/matrix-org/matrix-doc/issues/1600>`_)
|
||||
|
|
@ -554,7 +554,7 @@ Since the draft stage, the following major changes have been made:
|
|||
- Push notification
|
||||
- History visibility
|
||||
- Search
|
||||
- Invites based on third party identifiers
|
||||
- Invites based on third-party identifiers
|
||||
- Room tagging
|
||||
- Guest access
|
||||
- Client config
|
||||
|
|
|
|||
|
|
@ -48,7 +48,7 @@ r0.1.0
|
|||
======
|
||||
|
||||
This is the first release of the Identity Service API. With this API, clients and
|
||||
homeservers can store bindings between third party identifiers such as email addresses
|
||||
homeservers can store bindings between third-party identifiers such as email addresses
|
||||
and phone numbers, associating them with Matrix user IDs. Additionally, identity
|
||||
servers offer the ability to invite third party users to Matrix rooms by storing
|
||||
servers offer the ability to invite third-party users to Matrix rooms by storing
|
||||
the invite until the identifier is bound.
|
||||
|
|
|
|||
|
|
@ -1 +0,0 @@
|
|||
Add information on standard error responses for unknown endpoints/methods.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Update the default room version to 10, as per [MSC3904](https://github.com/matrix-org/matrix-spec-proposals/pull/3904).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add information on standard error responses for unknown endpoints/methods.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Include examples inline instead of using a reference for invite endpoint definitions.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Remove `keyId` from the server `/keys` endpoints, as per [MSC3938](https://github.com/matrix-org/matrix-spec-proposals/pull/3938).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix `POST _matrix/federation/v1/user/keys/claim` response schema.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add `/timestamp_to_event/<roomID>` endpoint, as per [MSC3030](https://github.com/matrix-org/matrix-spec-proposals/pull/3030).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Correct the default invite level definition in the "Checks performed on receipt of a PDU" section.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify that CNAMEs are permissible for server names.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix `edu_type` in EDU examples.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Extend `/_matrix/federation/v2/send_join` to allow omitting membership events, per [MSC3706](https://github.com/matrix-org/matrix-doc/pull/3706).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Extend `/_matrix/federation/v2/send_join` to allow omitting membership events, per [MSC3706](https://github.com/matrix-org/matrix-doc/pull/3706).
|
||||
|
|
@ -0,0 +1 @@
|
|||
Fix various typos throughout the specification.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Fix various typos throughout the specification.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Fix invalid OpenAPI specifications caused by overridden references to `examples/minimal_pdu.json`.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Fix various typos throughout the specification.
|
||||
|
|
@ -52,9 +52,9 @@ status = "unstable"
|
|||
current_version_url = "https://spec.matrix.org/latest"
|
||||
# The following is used when status = "stable", and is displayed in various UI elements on a released version
|
||||
# of the spec. CI will set these values here automatically when a release git tag (i.e `v1.5`) is created.
|
||||
#major = "1"
|
||||
#minor = "5"
|
||||
#release_date = "November 17, 2022"
|
||||
# major = "1"
|
||||
# minor = "6"
|
||||
# release_date = "February 14, 2023"
|
||||
|
||||
# User interface configuration
|
||||
[params.ui]
|
||||
|
|
|
|||
|
|
@ -372,7 +372,7 @@ servers that are in the room that can be used to join via.
|
|||
Users in Matrix are identified via their Matrix user ID. However,
|
||||
existing 3rd party ID namespaces can also be used in order to identify
|
||||
Matrix users. A Matrix "Identity" describes both the user ID and any
|
||||
other existing IDs from third party namespaces *linked* to their
|
||||
other existing IDs from third-party namespaces *linked* to their
|
||||
account. Matrix users can *link* third-party IDs (3PIDs) such as email
|
||||
addresses, social network accounts and phone numbers to their user ID.
|
||||
Linking 3PIDs creates a mapping from a 3PID to a user ID. This mapping
|
||||
|
|
|
|||
|
|
@ -83,7 +83,11 @@ object.
|
|||
|
||||
### Canonical JSON
|
||||
|
||||
We define the canonical JSON encoding for a value to be the shortest
|
||||
To ensure that all implementations use the same JSON encoding we define
|
||||
"Canonical JSON". This should not be confused with other uses of
|
||||
"Canonical JSON" outside of the specification.
|
||||
|
||||
We define this encoding for a value to be the shortest
|
||||
UTF-8 JSON encoding with dictionary keys lexicographically sorted by
|
||||
Unicode codepoint. Numbers in the JSON must be integers in the range
|
||||
`[-(2**53)+1, (2**53)-1]`.
|
||||
|
|
@ -892,7 +896,7 @@ unique servers based on the following criteria:
|
|||
|
||||
## 3PID Types
|
||||
|
||||
Third Party Identifiers (3PIDs) represent identifiers on other
|
||||
Third-party Identifiers (3PIDs) represent identifiers on other
|
||||
namespaces that might be associated with a particular person. They
|
||||
comprise a tuple of `medium` which is a string that identifies the
|
||||
namespace in which the identifier exists, and an `address`: a string
|
||||
|
|
@ -934,6 +938,14 @@ The `address` is the telephone number represented as a MSISDN (Mobile
|
|||
Station International Subscriber Directory Number) as defined by the
|
||||
E.164 numbering plan. Note that MSISDNs do not include a leading '+'.
|
||||
|
||||
## Glob-style matching
|
||||
|
||||
It is useful to match strings via globbing in some situations. Globbing in Matrix
|
||||
uses the following rules:
|
||||
|
||||
* The character `*` matches zero or more characters.
|
||||
* `?` matches exactly one character.
|
||||
|
||||
## Security Threat Model
|
||||
|
||||
### Denial of Service
|
||||
|
|
|
|||
|
|
@ -232,18 +232,18 @@ mappings.
|
|||
|
||||
{{% http-api spec="application-service" api="query_room" %}}
|
||||
|
||||
#### Third party networks
|
||||
#### Third-party networks
|
||||
|
||||
Application services may declare which protocols they support via their
|
||||
registration configuration for the homeserver. These networks are
|
||||
generally for third party services such as IRC that the application
|
||||
generally for third-party services such as IRC that the application
|
||||
service is managing. Application services may populate a Matrix room
|
||||
directory for their registered protocols, as defined in the
|
||||
Client-Server API Extensions.
|
||||
|
||||
Each protocol may have several "locations" (also known as "third party
|
||||
Each protocol may have several "locations" (also known as "third-party
|
||||
locations" or "3PLs"). A location within a protocol is a place in the
|
||||
third party network, such as an IRC channel. Users of the third party
|
||||
third-party network, such as an IRC channel. Users of the third-party
|
||||
network may also be represented by the application service.
|
||||
|
||||
Locations and users can be searched by fields defined by the application
|
||||
|
|
@ -399,13 +399,13 @@ the user implied by `sender_localpart`.
|
|||
#### Application service room directories
|
||||
|
||||
Application services can maintain their own room directories for their
|
||||
defined third party protocols. These room directories may be accessed by
|
||||
defined third-party protocols. These room directories may be accessed by
|
||||
clients through additional parameters on the `/publicRooms`
|
||||
client-server endpoint.
|
||||
|
||||
{{% http-api spec="client-server" api="appservice_room_directory" %}}
|
||||
|
||||
### Referencing messages from a third party network
|
||||
### Referencing messages from a third-party network
|
||||
|
||||
Application services should include an `external_url` in the `content`
|
||||
of events it emits to indicate where the message came from. This
|
||||
|
|
|
|||
135
content/changelog/v1.6.md
Normal file
135
content/changelog/v1.6.md
Normal file
|
|
@ -0,0 +1,135 @@
|
|||
---
|
||||
date: 2023-02-14T08:25:40-07:00
|
||||
---
|
||||
<!--
|
||||
This is a header file for the generated changelog.
|
||||
|
||||
Variables:
|
||||
v1.6 = Replaced by the version number (eg: v1.2)
|
||||
February 14, 2023 = Replaced by the date (eg: April 01, 2021)
|
||||
-->
|
||||
|
||||
## v1.6
|
||||
|
||||
<table class="release-info">
|
||||
<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.6">https://github.com/matrix-org/matrix-spec/tree/v1.6</a></td>
|
||||
<tr><th>Release date</th><td>February 14, 2023</td>
|
||||
</table>
|
||||
|
||||
<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
|
||||
### Client-Server API
|
||||
|
||||
|
||||
<strong>Backwards Compatible Changes</strong>
|
||||
|
||||
|
||||
- Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). ([#1347](https://github.com/matrix-org/matrix-spec/issues/1347))
|
||||
- Add `/rooms/<roomID>/timestamp_to_event` endpoint, as per [MSC3030](https://github.com/matrix-org/matrix-spec-proposals/pull/3030). ([#1366](https://github.com/matrix-org/matrix-spec/issues/1366))
|
||||
- Define `hkdf-hmac-sha256.v2` MAC method for SAS verification, as per [MSC3783](https://github.com/matrix-org/matrix-spec-proposals/pull/3783). ([#1412](https://github.com/matrix-org/matrix-spec/issues/1412))
|
||||
|
||||
|
||||
<strong>Spec Clarifications</strong>
|
||||
|
||||
|
||||
- Clarify the power levels integer range. ([#1169](https://github.com/matrix-org/matrix-spec/issues/1169), [#1355](https://github.com/matrix-org/matrix-spec/issues/1355))
|
||||
- Clarify that `/context` always returns `event` even if `limit` is zero. Contributed by @sumnerevans at @beeper. ([#1239](https://github.com/matrix-org/matrix-spec/issues/1239))
|
||||
- Clarify what fields are required when deleting a pusher ([#1321](https://github.com/matrix-org/matrix-spec/issues/1321))
|
||||
- Improve the presentation of push rule kinds and actions. ([#1348](https://github.com/matrix-org/matrix-spec/issues/1348))
|
||||
- Add missing description to m.call.answer schema. ([#1353](https://github.com/matrix-org/matrix-spec/issues/1353))
|
||||
- Fix various typos throughout the specification. ([#1363](https://github.com/matrix-org/matrix-spec/issues/1363))
|
||||
- Clarify parts of the end-to-end encryption sections. ([#1381](https://github.com/matrix-org/matrix-spec/issues/1381))
|
||||
- Move login API definitions to the right heading. Contributed by @HarHarLinks. ([#1382](https://github.com/matrix-org/matrix-spec/issues/1382))
|
||||
- Clarify which events will be included in Stripped State. Contributed by @andybalaam. ([#1409](https://github.com/matrix-org/matrix-spec/issues/1409))
|
||||
- Add links to the spec for the definition of 3PID `medium`. ([#1417](https://github.com/matrix-org/matrix-spec/issues/1417))
|
||||
- Correct the order of the default override pushrules in the spec. ([#1421](https://github.com/matrix-org/matrix-spec/issues/1421))
|
||||
- Improve distinction between tags and their attributes in the rich text section. Contributed by Nico. ([#1433](https://github.com/matrix-org/matrix-spec/issues/1433))
|
||||
|
||||
|
||||
### Server-Server API
|
||||
|
||||
|
||||
<strong>Breaking Changes</strong>
|
||||
|
||||
|
||||
- Remove `keyId` from the server `/keys` endpoints, as per [MSC3938](https://github.com/matrix-org/matrix-spec-proposals/pull/3938). ([#1350](https://github.com/matrix-org/matrix-spec/issues/1350))
|
||||
|
||||
|
||||
<strong>Backwards Compatible Changes</strong>
|
||||
|
||||
|
||||
- Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). ([#1347](https://github.com/matrix-org/matrix-spec/issues/1347))
|
||||
- Add `/timestamp_to_event/<roomID>` endpoint, as per [MSC3030](https://github.com/matrix-org/matrix-spec-proposals/pull/3030). ([#1366](https://github.com/matrix-org/matrix-spec/issues/1366))
|
||||
- Extend `/_matrix/federation/v2/send_join` to allow omitting membership events, per [MSC3706](https://github.com/matrix-org/matrix-doc/pull/3706). ([#1393](https://github.com/matrix-org/matrix-spec/issues/1393), [#1398](https://github.com/matrix-org/matrix-spec/issues/1398))
|
||||
- Note that `/_matrix/federation/v2/send_join` should include heroes for nameless rooms, even when allowed to omit membership events, per [MSC3943](https://github.com/matrix-org/matrix-doc/pull/3943). ([#1425](https://github.com/matrix-org/matrix-spec/issues/1425))
|
||||
|
||||
|
||||
<strong>Spec Clarifications</strong>
|
||||
|
||||
|
||||
- Include examples inline instead of using a reference for invite endpoint definitions. ([#1349](https://github.com/matrix-org/matrix-spec/issues/1349))
|
||||
- Fix `POST _matrix/federation/v1/user/keys/claim` response schema. ([#1351](https://github.com/matrix-org/matrix-spec/issues/1351))
|
||||
- Correct the default invite level definition in the "Checks performed on receipt of a PDU" section. ([#1371](https://github.com/matrix-org/matrix-spec/issues/1371))
|
||||
- Clarify that CNAMEs are permissible for server names. ([#1376](https://github.com/matrix-org/matrix-spec/issues/1376))
|
||||
- Fix `edu_type` in EDU examples. ([#1383](https://github.com/matrix-org/matrix-spec/issues/1383))
|
||||
|
||||
|
||||
### Application Service API
|
||||
|
||||
|
||||
<strong>Backwards Compatible Changes</strong>
|
||||
|
||||
|
||||
- Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). ([#1347](https://github.com/matrix-org/matrix-spec/issues/1347))
|
||||
|
||||
|
||||
### Identity Service API
|
||||
|
||||
|
||||
<strong>Backwards Compatible Changes</strong>
|
||||
|
||||
|
||||
- Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). ([#1347](https://github.com/matrix-org/matrix-spec/issues/1347))
|
||||
|
||||
|
||||
### Push Gateway API
|
||||
|
||||
|
||||
<strong>Backwards Compatible Changes</strong>
|
||||
|
||||
|
||||
- Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). ([#1347](https://github.com/matrix-org/matrix-spec/issues/1347))
|
||||
|
||||
|
||||
### Room Versions
|
||||
|
||||
|
||||
<strong>Backwards Compatible Changes</strong>
|
||||
|
||||
|
||||
- Update the default room version to 10, as per [MSC3904](https://github.com/matrix-org/matrix-spec-proposals/pull/3904). ([#1397](https://github.com/matrix-org/matrix-spec/issues/1397))
|
||||
|
||||
|
||||
<strong>Spec Clarifications</strong>
|
||||
|
||||
|
||||
- Clarify the grammar for room versions. ([#1422](https://github.com/matrix-org/matrix-spec/issues/1422))
|
||||
- Fix various typos throughout the specification. ([#1423](https://github.com/matrix-org/matrix-spec/issues/1423))
|
||||
|
||||
|
||||
### Appendices
|
||||
|
||||
|
||||
No significant changes.
|
||||
|
||||
|
||||
### Internal Changes/Tooling
|
||||
|
||||
|
||||
<strong>Spec Clarifications</strong>
|
||||
|
||||
|
||||
- Add link to the unstable spec to the README. ([#1357](https://github.com/matrix-org/matrix-spec/issues/1357))
|
||||
- Improve safety of the proposals retrieval script in the event of failure. ([#1368](https://github.com/matrix-org/matrix-spec/issues/1368))
|
||||
- Rename `<content>` to `content` in the OpenAPI files for content uploads. ([#1370](https://github.com/matrix-org/matrix-spec/issues/1370))
|
||||
- Stop autogenerating examples where we already have an example. ([#1384](https://github.com/matrix-org/matrix-spec/issues/1384))
|
||||
- Improve formatting of definitions in the Push Notifications section. ([#1415](https://github.com/matrix-org/matrix-spec/issues/1415))
|
||||
|
|
@ -150,15 +150,15 @@ Sent when a threepid given to an API cannot be used because no record
|
|||
matching the threepid was found.
|
||||
|
||||
`M_THREEPID_AUTH_FAILED`
|
||||
Authentication could not be performed on the third party identifier.
|
||||
Authentication could not be performed on the third-party identifier.
|
||||
|
||||
`M_THREEPID_DENIED`
|
||||
The server does not permit this third party identifier. This may happen
|
||||
The server does not permit this third-party identifier. This may happen
|
||||
if the server only permits, for example, email addresses from a
|
||||
particular domain.
|
||||
|
||||
`M_SERVER_NOT_TRUSTED`
|
||||
The client's request used a third party server, e.g. identity server,
|
||||
The client's request used a third-party server, e.g. identity server,
|
||||
that this server does not trust.
|
||||
|
||||
`M_UNSUPPORTED_ROOM_VERSION`
|
||||
|
|
@ -214,19 +214,36 @@ See the [Server Notices](#server-notices) module for more information.
|
|||
### Transaction identifiers
|
||||
|
||||
The client-server API typically uses `HTTP PUT` to submit requests with
|
||||
a client-generated transaction identifier. This means that these
|
||||
requests are idempotent. It **only** serves to identify new requests
|
||||
from retransmits. After the request has finished, the `{txnId}` value
|
||||
should be changed (how is not specified; a monotonically increasing
|
||||
integer is recommended).
|
||||
a client-generated transaction identifier in the HTTP path.
|
||||
|
||||
The scope of a transaction ID is a "client session", where that session
|
||||
is identified by a particular access token. When [refreshing](#refreshing-access-tokens)
|
||||
an access token, the transaction ID's scope is retained. This means that
|
||||
if a client with token `A` uses `TXN1` as their transaction ID, refreshes
|
||||
the token to `B`, and uses `TXN1` again it'll be assumed to be a duplicate
|
||||
request and ignored. If the client logs out and back in between the `A` and
|
||||
`B` tokens, `TXN1` could be used once for each.
|
||||
The purpose of the transaction ID is to allow the homeserver to distinguish a
|
||||
new request from a retransmission of a previous request so that it can make
|
||||
the request idempotent.
|
||||
|
||||
The transaction ID should **only** be used for this purpose.
|
||||
|
||||
From the client perspective, after the request has finished, the `{txnId}`
|
||||
value should be changed by for the next request (how is not specified; a
|
||||
monotonically increasing integer is recommended).
|
||||
|
||||
The homeserver should identify a request as a retransmission if the
|
||||
transaction ID is the same as a previous request, and the path of the
|
||||
HTTP request is the same.
|
||||
|
||||
Where a retransmission has been identified, the homeserver should return
|
||||
the same HTTP response code and content as the original request.
|
||||
For example, `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`
|
||||
would return a `200 OK` with the `event_id` of the original request in
|
||||
the response body.
|
||||
|
||||
As well as the HTTP path, the scope of a transaction ID is a "client
|
||||
session", where that session is identified by a particular access token.
|
||||
When [refreshing](#refreshing-access-tokens) an access token, the
|
||||
transaction ID's scope is retained. This means that if a client with
|
||||
token `A` uses `TXN1` as their transaction ID, refreshes the token to
|
||||
`B`, and uses `TXN1` again it'll be assumed to be a duplicate request
|
||||
and ignored. If the client logs out and back in between the `A` and `B`
|
||||
tokens, `TXN1` could be used once for each.
|
||||
|
||||
Some API endpoints may allow or require the use of `POST` requests
|
||||
without a transaction ID. Where this is optional, the use of a `PUT`
|
||||
|
|
@ -739,7 +756,7 @@ submit:
|
|||
```
|
||||
|
||||
Alternatively reply using a 3PID bound to the user's account on the
|
||||
homeserver using the `/account/3pid`\_ API rather than giving the `user`
|
||||
homeserver using the [`/account/3pid`](#get_matrixclientv3account3pid) API rather than giving the `user`
|
||||
explicitly as follows:
|
||||
|
||||
```json
|
||||
|
|
@ -747,8 +764,8 @@ explicitly as follows:
|
|||
"type": "m.login.password",
|
||||
"identifier": {
|
||||
"type": "m.id.thirdparty",
|
||||
"medium": "<The medium of the third party identifier.>",
|
||||
"address": "<The third party address of the user>"
|
||||
"medium": "<The medium of the third-party identifier.>",
|
||||
"address": "<The third-party address of the user>"
|
||||
},
|
||||
"password": "<password>",
|
||||
"session": "<session ID>"
|
||||
|
|
@ -1047,15 +1064,15 @@ ID.
|
|||
|
||||
A client can identify a user using a 3PID associated with the user's
|
||||
account on the homeserver, where the 3PID was previously associated
|
||||
using the `/account/3pid`\_ API. See the [3PID
|
||||
using the [`/account/3pid`](#get_matrixclientv3account3pid) API. See the [3PID
|
||||
Types](/appendices#3pid-types) Appendix for a list of Third-party
|
||||
ID media.
|
||||
|
||||
```json
|
||||
"identifier": {
|
||||
"type": "m.id.thirdparty",
|
||||
"medium": "<The medium of the third party identifier>",
|
||||
"address": "<The canonicalised third party address of the user>"
|
||||
"medium": "<The medium of the third-party identifier>",
|
||||
"address": "<The canonicalised third-party address of the user>"
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -1067,7 +1084,7 @@ ID media.
|
|||
|
||||
A client can identify a user using a phone number associated with the
|
||||
user's account, where the phone number was previously associated using
|
||||
the `/account/3pid`\_ API. The phone number can be passed in as entered
|
||||
the [`/account/3pid`](#get_matrixclientv3account3pid) API. The phone number can be passed in as entered
|
||||
by the user; the homeserver will be responsible for canonicalising it.
|
||||
If the client wishes to canonicalise the phone number, then it can use
|
||||
the `m.id.thirdparty` identifier type with a `medium` of `msisdn`
|
||||
|
|
@ -1108,15 +1125,15 @@ request as follows:
|
|||
```
|
||||
|
||||
Alternatively, a client can use a 3PID bound to the user's account on
|
||||
the homeserver using the `/account/3pid`\_ API rather than giving the
|
||||
the homeserver using the [`/account/3pid`](#get_matrixclientv3account3pid) API rather than giving the
|
||||
`user` explicitly, as follows:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "m.login.password",
|
||||
"identifier": {
|
||||
"medium": "<The medium of the third party identifier>",
|
||||
"address": "<The canonicalised third party address of the user>"
|
||||
"medium": "<The medium of the third-party identifier>",
|
||||
"address": "<The canonicalised third-party address of the user>"
|
||||
},
|
||||
"password": "<password>"
|
||||
}
|
||||
|
|
@ -1241,7 +1258,7 @@ can be added and bound at the same time, depending on context.
|
|||
#### Notes on identity servers
|
||||
|
||||
Identity servers in Matrix store bindings (relationships) between a
|
||||
user's third party identifier, typically email or phone number, and
|
||||
user's third-party identifier, typically email or phone number, and
|
||||
their user ID. Once a user has chosen an identity server, that identity
|
||||
server should be used by all clients.
|
||||
|
||||
|
|
@ -1579,15 +1596,18 @@ detail on why this assumption is unsafe.
|
|||
|
||||
### Stripped state
|
||||
|
||||
Stripped state events are simplified state events to help a potential
|
||||
joiner identify the room. These state events can only have the `sender`,
|
||||
`type`, `state_key` and `content` keys present.
|
||||
Stripped state is a simplified view of the state of a room intended to help a
|
||||
potential joiner identify the room. It consists of a limited set of state events
|
||||
that are themselves simplified to reduce the amount of data required.
|
||||
|
||||
These stripped state events typically appear on invites, knocks, and in
|
||||
other places where a user *could* join the room under the conditions
|
||||
available (such as a [`restricted` room](#restricted-rooms)).
|
||||
Stripped state events can only have the `sender`, `type`, `state_key` and
|
||||
`content` properties present.
|
||||
|
||||
Clients should only use stripped state events so long as they don't have
|
||||
Stripped state typically appears in invites, knocks, and in other places where a
|
||||
user *could* join the room under the conditions available (such as a
|
||||
[`restricted` room](#restricted-rooms)).
|
||||
|
||||
Clients should only use stripped state events when they don't have
|
||||
access to the proper state of the room. Once the state of the room is
|
||||
available, all stripped state should be discarded. In cases where the
|
||||
client has an archived state of the room (such as after being kicked)
|
||||
|
|
@ -1595,8 +1615,8 @@ and the client is receiving stripped state for the room, such as from an
|
|||
invite or knock, then the stripped state should take precedence until
|
||||
fresh state can be acquired from a join.
|
||||
|
||||
The following state events should be represented as stripped state when
|
||||
possible:
|
||||
Stripped state should contain some or all of the following state events, which
|
||||
should be represented as stripped state events when possible:
|
||||
|
||||
* [`m.room.create`](#mroomcreate)
|
||||
* [`m.room.name`](#mroomname)
|
||||
|
|
@ -2544,7 +2564,7 @@ that profile.
|
|||
| [Room Upgrades](#room-upgrades) | Required | Required | Required | Required | Optional |
|
||||
| [Server Administration](#server-administration) | Optional | Optional | Optional | Optional | Optional |
|
||||
| [Event Context](#event-context) | Optional | Optional | Optional | Optional | Optional |
|
||||
| [Third Party Networks](#third-party-networks) | Optional | Optional | Optional | Optional | Optional |
|
||||
| [Third-party Networks](#third-party-networks) | Optional | Optional | Optional | Optional | Optional |
|
||||
| [Send-to-Device Messaging](#send-to-device-messaging) | Optional | Optional | Optional | Optional | Optional |
|
||||
| [Device Management](#device-management) | Optional | Optional | Optional | Optional | Optional |
|
||||
| [End-to-End Encryption](#end-to-end-encryption) | Optional | Optional | Optional | Optional | Optional |
|
||||
|
|
|
|||
|
|
@ -668,22 +668,22 @@ The process between Alice and Bob verifying each other would be:
|
|||
the users to select a method.
|
||||
14. Alice and Bob compare the strings shown by their devices, and tell
|
||||
their devices if they match or not.
|
||||
15. Assuming they match, Alice and Bob's devices calculate the HMAC of
|
||||
their own device keys and a comma-separated sorted list of the key
|
||||
IDs that they wish the other user to verify, using SHA-256 as the
|
||||
hash function. HMAC is defined in [RFC
|
||||
2104](https://tools.ietf.org/html/rfc2104). The key for the HMAC is
|
||||
different for each item and is calculated by generating 32 bytes
|
||||
(256 bits) using [the key verification HKDF](#hkdf-calculation).
|
||||
15. Assuming they match, Alice and Bob's devices each calculate Message
|
||||
Authentication Codes (MACs) for:
|
||||
* Each of the keys that they wish the other user to verify (usually their
|
||||
device ed25519 key and their master cross-signing key).
|
||||
* The complete list of key IDs that they wish the other user to verify.
|
||||
|
||||
The MAC calculation is defined [below](#mac-calculation).
|
||||
16. Alice's device sends Bob's device an `m.key.verification.mac`
|
||||
message containing the MAC of Alice's device keys and the MAC of her
|
||||
key IDs to be verified. Bob's device does the same for Bob's device
|
||||
keys and key IDs concurrently with Alice.
|
||||
17. When the other device receives the `m.key.verification.mac` message,
|
||||
the device calculates the HMAC of its copies of the other device's
|
||||
keys given in the message, as well as the HMAC of the
|
||||
the device calculates the MACs of its copies of the other device's
|
||||
keys given in the message, as well as the MAC of the
|
||||
comma-separated, sorted, list of key IDs in the message. The device
|
||||
compares these with the HMAC values given in the message, and if
|
||||
compares these with the MAC values given in the message, and if
|
||||
everything matches then the device keys are verified.
|
||||
18. Alice and Bob's devices send `m.key.verification.done` messages to complete
|
||||
the verification.
|
||||
|
|
@ -767,7 +767,55 @@ following error codes are used in addition to those already specified:
|
|||
|
||||
{{% event event="m.key.verification.mac" %}}
|
||||
|
||||
###### HKDF calculation
|
||||
###### MAC calculation
|
||||
|
||||
During the verification process, Message Authentication Codes (MACs) are calculated
|
||||
for keys and lists of key IDs.
|
||||
|
||||
The method used to calculate these MACs depends upon the value of the
|
||||
`message_authentication_code` property in the [`m.key.verification.accept`](#mkeyverificationaccept)
|
||||
message. All current implementations should use the `hkdf-hmac-sha256.v2` method which is
|
||||
defined as follows:
|
||||
|
||||
The MAC used is HMAC as defined in [RFC
|
||||
5869](https://tools.ietf.org/html/rfc5869), using SHA-256 as the hash
|
||||
function. The shared secret is supplied as the input keying material. No salt
|
||||
is used, and in the info parameter is the concatenation of:
|
||||
|
||||
- The string `MATRIX_KEY_VERIFICATION_MAC`.
|
||||
- The Matrix ID of the user whose key is being MAC-ed.
|
||||
- The Device ID of the device sending the MAC.
|
||||
- The Matrix ID of the other user.
|
||||
- The Device ID of the device receiving the MAC.
|
||||
- The `transaction_id` being used.
|
||||
- The Key ID of the key being MAC-ed, or the string `KEY_IDS` if the
|
||||
item being MAC-ed is the list of key IDs.
|
||||
|
||||
If a key is being MACed, the MAC is performed on the public key as encoded
|
||||
according to the [key algorithm](#key-algorithms). For example, for `ed25519`
|
||||
keys, it is the unpadded base64-encoded key.
|
||||
|
||||
If the key list is being MACed, the list is sorted lexicographically and
|
||||
comma-separated with no extra whitespace added, with each key written in the
|
||||
form `{algorithm}:{keyId}`. For example, the key list could look like:
|
||||
`ed25519:Cross+Signing+Key,ed25519:DEVICEID`. In this way, the recipient can
|
||||
reconstruct the list from the names in the `mac` property of the
|
||||
`m.key.verification.mac` message and ensure that no keys were added or removed.
|
||||
|
||||
The MAC values are base64-encoded and sent in a
|
||||
[`m.key.verification.mac`](#mkeyverificationmac) message.
|
||||
|
||||
{{% boxes/note %}}
|
||||
The MAC method `hkdf-hmac-sha256` used an incorrect base64 encoding, due to a
|
||||
bug in the original implementation in libolm. To remedy this,
|
||||
`hkdf-hmac-sha256.v2` was introduced, which calculates the MAC in the same way,
|
||||
but uses a correct base64 encoding. `hkdf-hmac-sha256` is deprecated and will
|
||||
be removed in a future version of the spec. Use of `hkdf-hmac-sha256` should
|
||||
be avoided whenever possible: if both parties support `hkdf-hmac-sha256.v2`,
|
||||
then `hkdf-hmac-sha256` MUST not be used.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
###### SAS HKDF calculation
|
||||
|
||||
In all of the SAS methods, HKDF is as defined in [RFC
|
||||
5869](https://tools.ietf.org/html/rfc5869) and uses the previously
|
||||
|
|
@ -815,23 +863,9 @@ HKDF is used over the plain shared secret as it results in a harder
|
|||
attack as well as more uniform data to work with.
|
||||
{{% /boxes/rationale %}}
|
||||
|
||||
For verification of each party's device keys, HKDF is as defined in RFC
|
||||
5869 and uses SHA-256 as the hash function. The shared secret is
|
||||
supplied as the input keying material. No salt is used, and in the info
|
||||
parameter is the concatenation of:
|
||||
|
||||
- The string `MATRIX_KEY_VERIFICATION_MAC`.
|
||||
- The Matrix ID of the user whose key is being MAC-ed.
|
||||
- The Device ID of the device sending the MAC.
|
||||
- The Matrix ID of the other user.
|
||||
- The Device ID of the device receiving the MAC.
|
||||
- The `transaction_id` being used.
|
||||
- The Key ID of the key being MAC-ed, or the string `KEY_IDS` if the
|
||||
item being MAC-ed is the list of key IDs.
|
||||
|
||||
###### SAS method: `decimal`
|
||||
|
||||
Generate 5 bytes using [HKDF](#hkdf-calculation) then take sequences of 13 bits
|
||||
Generate 5 bytes using [HKDF](#sas-hkdf-calculation) then take sequences of 13 bits
|
||||
to convert to decimal numbers (resulting in 3 numbers between 0 and 8191
|
||||
inclusive each). Add 1000 to each calculated number.
|
||||
|
||||
|
|
@ -849,7 +883,7 @@ separator, such as dashes, or with the numbers on individual lines.
|
|||
|
||||
###### SAS method: `emoji`
|
||||
|
||||
Generate 6 bytes using [HKDF](#hkdf-calculation) then split the first 42 bits
|
||||
Generate 6 bytes using [HKDF](#sas-hkdf-calculation) then split the first 42 bits
|
||||
into 7 groups of 6 bits, similar to how one would base64 encode
|
||||
something. Convert each group of 6 bits to a number and use the
|
||||
following table to get the corresponding emoji:
|
||||
|
|
|
|||
|
|
@ -133,13 +133,6 @@ being overwritten entirely by `m.new_content`, with the exception of `m.relates_
|
|||
which is left *unchanged*. Any `m.relates_to` property within `m.new_content`
|
||||
is ignored.
|
||||
|
||||
{{% boxes/note %}}
|
||||
Note that server implementations must not *actually* overwrite
|
||||
the original event's `content`: instead the server presents it as being overwritten
|
||||
when it is served over the client-server API. See [Server-side replacement of content](#server-side-replacement-of-content)
|
||||
below.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
For example, given a pair of events:
|
||||
|
||||
```json
|
||||
|
|
@ -195,14 +188,17 @@ replacement event.
|
|||
|
||||
##### Server-side aggregation of `m.replace` relationships
|
||||
|
||||
{{< changed-in v="1.7" >}}
|
||||
|
||||
Note that there can be multiple events with an `m.replace` relationship to a
|
||||
given event (for example, if an event is edited multiple times). These should
|
||||
be [aggregated](#aggregations-of-child-events) by the homeserver.
|
||||
|
||||
The aggregation format of `m.replace` relationships gives the `event_id`,
|
||||
`origin_server_ts`, and `sender` of the **most recent** replacement event. The
|
||||
most recent event is determined by comparing `origin_server_ts`; if two or more
|
||||
replacement events have identical `origin_server_ts`, the event with the
|
||||
The aggregation format of `m.replace` relationships gives the **most recent**
|
||||
replacement event, formatted [as normal](#room-event-format).
|
||||
|
||||
The most recent event is determined by comparing `origin_server_ts`; if two or
|
||||
more replacement events have identical `origin_server_ts`, the event with the
|
||||
lexicographically largest `event_id` is treated as more recent.
|
||||
|
||||
As with any other aggregation of child events, the `m.replace` aggregation is
|
||||
|
|
@ -212,49 +208,61 @@ the target of an `m.replace` relationship. For example:
|
|||
```json
|
||||
{
|
||||
"event_id": "$original_event_id",
|
||||
// irrelevant fields not shown
|
||||
"type": "m.room.message",
|
||||
"content": {
|
||||
"body": "I really like cake",
|
||||
"msgtype": "m.text",
|
||||
"formatted_body": "I really like cake"
|
||||
},
|
||||
"unsigned": {
|
||||
"m.relations": {
|
||||
"m.replace": {
|
||||
"event_id": "$latest_edit_event_id",
|
||||
"origin_server_ts": 1649772304313,
|
||||
"sender": "@editing_user:localhost"
|
||||
"type": "m.room.message",
|
||||
"content": {
|
||||
"body": "* I really like *chocolate* cake",
|
||||
"msgtype": "m.text",
|
||||
"m.new_content": {
|
||||
"body": "I really like *chocolate* cake",
|
||||
"msgtype": "m.text"
|
||||
},
|
||||
"m.relates_to": {
|
||||
"rel_type": "m.replace",
|
||||
"event_id": "$original_event_id"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
// irrelevant fields not shown
|
||||
}
|
||||
```
|
||||
|
||||
However, if the original event is [redacted](#redactions), any replacement
|
||||
events are *not* aggregated and `m.replace` is omitted from the aggregation
|
||||
returned under `m.relations` (whether or not any subsequent replacements are
|
||||
themselves redacted). Note that this behaviour is specific to the `m.replace`
|
||||
relationship. See also [redactions of edited
|
||||
If the original event is [redacted](#redactions), any
|
||||
`m.replace` relationship should **not** be bundled with it (whether or not any
|
||||
subsequent replacements are themselves redacted). Note that this behaviour is
|
||||
specific to the `m.replace` relationship. See also [redactions of edited
|
||||
events](#redactions-of-edited-events) below.
|
||||
|
||||
##### Server-side replacement of content
|
||||
**Note:** the `content` of the original event is left intact. In particular servers
|
||||
should **not** replace the content with that of the replacement event.
|
||||
|
||||
Whenever an `m.replace` is to be bundled with its parent event as above, the server
|
||||
should also modify the content of the original event according to the
|
||||
`m.new_content` of the most recent replacement event (determined as above).
|
||||
|
||||
An exception applies to [`GET /_matrix/client/v3/rooms/{roomId}/event/{eventId}`](#get_matrixclientv3roomsroomideventeventid),
|
||||
which should return the unmodified event (though the replacement event should still
|
||||
be included under `m.relations`, as described above).
|
||||
{{ boxes/rationale }}
|
||||
In previous versions of the specification, servers were expected to replace the
|
||||
content of an edited event whenever it was served to clients (with the
|
||||
exception of the
|
||||
[`GET /_matrix/client/v3/rooms/{roomId}/event/{eventId}`](#get_matrixclientv3roomsroomideventeventid)
|
||||
endpoint). However, that behaviour made reliable client-side implementation
|
||||
difficult, and servers should no longer make this replacement.
|
||||
{{ /boxes/rationale }}
|
||||
|
||||
#### Client behaviour
|
||||
|
||||
Clients can often ignore `m.replace` events, because any events returned
|
||||
by the server to the client will be updated by the server to account for
|
||||
subsequent edits.
|
||||
|
||||
However, clients should apply the replacement themselves when the server is
|
||||
unable to do so. This happens in the following situations:
|
||||
|
||||
* The client has already received and stored the original event before the
|
||||
message edit event arrives.
|
||||
|
||||
* The original event (and hence its replacement) are encrypted.
|
||||
Since the server will not replace the content of any edited events, clients
|
||||
should take note of any replacement events they receive, and apply the
|
||||
replacement whenever possible and appropriate.
|
||||
|
||||
Client authors are reminded to take note of the requirements for [Validity of
|
||||
replacement events](#validity-of-replacement-events), and to ignore any
|
||||
|
|
|
|||
|
|
@ -48,27 +48,14 @@ are listed, clients should translate the value (a `#` character followed
|
|||
by a 6-character hex color code) to the appropriate CSS/attributes for
|
||||
the tag.
|
||||
|
||||
`font`
|
||||
`data-mx-bg-color`, `data-mx-color`, `color`
|
||||
|
||||
`span`
|
||||
`data-mx-bg-color`, `data-mx-color`, `data-mx-spoiler` (see
|
||||
[spoiler messages](#spoiler-messages))
|
||||
|
||||
`a`
|
||||
`name`, `target`, `href` (provided the value is not relative and has a
|
||||
scheme matching one of: `https`, `http`, `ftp`, `mailto`, `magnet`)
|
||||
|
||||
`img`
|
||||
`width`, `height`, `alt`, `title`, `src` (provided it is a [Matrix
|
||||
Content (MXC) URI](#matrix-content-mxc-uris))
|
||||
|
||||
`ol`
|
||||
`start`
|
||||
|
||||
`code`
|
||||
`class` (only classes which start with `language-` for syntax
|
||||
highlighting)
|
||||
| Tag | Permitted Attributes |
|
||||
|--------|--------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `font` | `data-mx-bg-color`, `data-mx-color`, `color` |
|
||||
| `span` | `data-mx-bg-color`, `data-mx-color`, `data-mx-spoiler` (see [spoiler messages](#spoiler-messages)) |
|
||||
| `a` | `name`, `target`, `href` (provided the value is not relative and has a scheme matching one of: `https`, `http`, `ftp`, `mailto`, `magnet`) |
|
||||
| `img` | `width`, `height`, `alt`, `title`, `src` (provided it is a [Matrix Content (MXC) URI](#matrix-content-mxc-uris)) |
|
||||
| `ol` | `start` |
|
||||
| `code` | `class` (only classes which start with `language-` for syntax highlighting) |
|
||||
|
||||
Additionally, web clients should ensure that *all* `a` tags get a
|
||||
`rel="noopener"` to prevent the target page from referencing the
|
||||
|
|
|
|||
|
|
@ -75,8 +75,8 @@ technique for receiving updates to the policy's rules.
|
|||
|
||||
#### Events
|
||||
|
||||
The `entity` described by the state events can contain `*` and `?` to
|
||||
match zero or more characters and exactly one character respectively. Note that
|
||||
The `entity` described by the state events is interpreted as a
|
||||
[glob-style pattern](/appendices#glob-style-matching). Note that
|
||||
rules against rooms can describe a room ID or room alias - the
|
||||
subscriber is responsible for resolving the alias to a room ID if
|
||||
desired.
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
|
||||
### OpenID
|
||||
|
||||
This module allows users to verify their identity with a third party
|
||||
service. The third party service does need to be matrix-aware in that it
|
||||
This module allows users to verify their identity with a third-party
|
||||
service. The third-party service does need to be matrix-aware in that it
|
||||
will need to know to resolve matrix homeservers to exchange the user's
|
||||
token for identity information.
|
||||
|
||||
|
|
|
|||
|
|
@ -85,58 +85,7 @@ Push Ruleset
|
|||
sender, a particular room, or by default. The push ruleset contains the
|
||||
entire set of scopes and rules.
|
||||
|
||||
#### Client behaviour
|
||||
|
||||
Clients MUST configure a Pusher before they will receive push
|
||||
notifications. There is a single API endpoint for this, as described
|
||||
below.
|
||||
|
||||
{{% http-api spec="client-server" api="pusher" %}}
|
||||
|
||||
##### Listing Notifications
|
||||
|
||||
A client can retrieve a list of events that it has been notified about.
|
||||
This may be useful so that users can see a summary of what important
|
||||
messages they have received.
|
||||
|
||||
{{% http-api spec="client-server" api="notifications" %}}
|
||||
|
||||
##### Receiving notifications
|
||||
|
||||
Servers MUST include the number of unread notifications in a client's
|
||||
`/sync` stream, and MUST update it as it changes. Notifications are
|
||||
determined by the push rules which apply to an event.
|
||||
|
||||
When the user updates their read receipt (either by using the API or by
|
||||
sending an event), notifications prior to and including that event MUST
|
||||
be marked as read. Which specific events are affected can vary depending
|
||||
on whether a [threaded read receipt](#threaded-read-receipts) was used.
|
||||
Note that users can send both an `m.read` and `m.read.private` receipt,
|
||||
both of which are capable of clearing notifications.
|
||||
|
||||
If the user has both `m.read` and `m.read.private` set in the room then
|
||||
the receipt which is more recent/ahead must be used to determine where
|
||||
the user has read up to. For example, given an oldest-first set of events A,
|
||||
B, C, and D the `m.read` receipt could be at event C and `m.read.private`
|
||||
at event A - the user is considered to have read up to event C. If the
|
||||
`m.read.private` receipt is then updated to point to B or C, the user's
|
||||
notification state doesn't change (the `m.read` receipt is still more
|
||||
ahead), however if the `m.read.private` receipt were to be updated to
|
||||
event D then the user has read up to D (the `m.read` receipt is now
|
||||
behind the `m.read.private` receipt).
|
||||
|
||||
{{< added-in v="1.4" >}} When handling threaded read receipts, the server
|
||||
is to partition the notification count to each thread (with the main timeline
|
||||
being its own thread). To determine if an event is part of a thread the
|
||||
server follows the [event relationship](#forming-relationships-between-events)
|
||||
until it finds a thread root (as specified by the [threading module](#threading)),
|
||||
however it is not recommended that the server traverse infinitely. Instead,
|
||||
implementations are encouraged to do a maximum of 3 hops to find a thread
|
||||
before deciding that the event does not belong to a thread. This is primarily
|
||||
to ensure that future events, like `m.reaction`, are correctly considered
|
||||
"part of" a given thread.
|
||||
|
||||
##### Push Rules
|
||||
#### Push Rules
|
||||
|
||||
A push rule is a single rule that states under what *conditions* an
|
||||
event should be passed onto a push gateway and *how* the notification
|
||||
|
|
@ -153,10 +102,14 @@ The different `kind`s of rule, in the order that they are checked, are:
|
|||
The highest priority rules are user-configured overrides.
|
||||
|
||||
1. **Content-specific rules (`content`).**
|
||||
These configure behaviour for (unencrypted) messages that match certain
|
||||
patterns. Content rules take one parameter: `pattern`, that gives the
|
||||
glob pattern to match against. This is treated in the same way as
|
||||
`pattern` for `event_match`.
|
||||
These configure behaviour for messages that match certain patterns. Content
|
||||
rules take one parameter: `pattern`, that gives the
|
||||
[glob-style pattern](/appendices#glob-style-matching) to match against.
|
||||
The match is performed case-insensitively, and must match any substring of
|
||||
the `content.body` property which starts and ends at a word boundary. A word
|
||||
boundary is defined as the start or end of the value, or any character not
|
||||
in the sets `[A-Z]`, `[a-z]`, `[0-9]` or `_`.The exact meaning of
|
||||
"case insensitive" is defined by the implementation of the homeserver.
|
||||
|
||||
1. **Room-specific rules (`room`).**
|
||||
These rules change the behaviour of all messages for a given room. The
|
||||
|
|
@ -184,7 +137,7 @@ rules match an event, the homeserver MUST NOT notify the Push Gateway
|
|||
for that event. Homeservers MUST NOT notify the Push Gateway for events
|
||||
that the user has sent themselves.
|
||||
|
||||
###### Actions
|
||||
##### Actions
|
||||
|
||||
All rules have an associated list of `actions`. An action affects if and
|
||||
how a notification is delivered for a matching event. The following
|
||||
|
|
@ -242,7 +195,7 @@ they are represented as a dictionary with a key equal to their name and
|
|||
other keys as their parameters, e.g.
|
||||
`{ "set_tweak": "sound", "value": "default" }`.
|
||||
|
||||
###### Conditions
|
||||
##### Conditions
|
||||
|
||||
`override` and `underride` rules MAY have a list of 'conditions'. All
|
||||
conditions must hold true for an event in order for the rule to match. A
|
||||
|
|
@ -264,18 +217,13 @@ This is a glob pattern match on a field of the event. Parameters:
|
|||
- `key`: The dot-separated path of the property of the event to match, e.g.
|
||||
`content.body`.
|
||||
|
||||
- `pattern`: The glob-style pattern to match against.
|
||||
- `pattern`: The [glob-style pattern](/appendices#glob-style-matching) to match against.
|
||||
|
||||
The match is performed case-insensitively, and must match the entire value of
|
||||
the event field given by `key` (though see below regarding `content.body`). The
|
||||
exact meaning of "case insensitive" is defined by the implementation of the
|
||||
homeserver.
|
||||
|
||||
Within `pattern`:
|
||||
|
||||
* The character `*` matches zero or more characters.
|
||||
* `?` matches exactly one character.
|
||||
|
||||
If the property specified by `key` is completely absent from the event, or does
|
||||
not have a string value, then the condition will not match, even if `pattern`
|
||||
is `*`.
|
||||
|
|
@ -301,7 +249,7 @@ Other `topic` values which will match are:
|
|||
|
||||
* `"LUNCH"` (case-insensitive; `*` may match zero characters)
|
||||
|
||||
The following `membership` values will NOT match:
|
||||
The following `topic` values will NOT match:
|
||||
* `" lunch"` (note leading space)
|
||||
* `"lunc"` (`?` must match a character)
|
||||
* `null` (not a string)
|
||||
|
|
@ -347,10 +295,10 @@ For an example of this, see the default rule
|
|||
|
||||
**`contains_display_name`**
|
||||
|
||||
This matches unencrypted messages where `content.body` contains the
|
||||
owner's display name in that room. This is a separate rule because
|
||||
display names may change and as such it would be hard to maintain a rule
|
||||
that matched the user's display name. This condition has no parameters.
|
||||
This matches messages where `content.body` contains the owner's display name in
|
||||
that room. This is a separate condition because display names may change and as such
|
||||
it would be hard to maintain a rule that matched the user's display name. This
|
||||
condition has no parameters.
|
||||
|
||||
**`room_member_count`**
|
||||
|
||||
|
|
@ -376,7 +324,7 @@ Parameters:
|
|||
to look up the power level required to send a notification type from
|
||||
the `notifications` object in the power level event content.
|
||||
|
||||
##### Predefined Rules
|
||||
#### Predefined Rules
|
||||
|
||||
Homeservers can specify "server-default rules". They operate at a lower
|
||||
priority than "user-defined rules", except for the `.m.rule.master` rule
|
||||
|
|
@ -385,7 +333,7 @@ for all server-default rules MUST start with a dot (".") to identify
|
|||
them as "server-default". The following server-default rules are
|
||||
specified:
|
||||
|
||||
###### Default Override Rules
|
||||
##### Default Override Rules
|
||||
|
||||
**`.m.rule.master`**
|
||||
|
||||
|
|
@ -496,8 +444,8 @@ Definition:
|
|||
|
||||
**`.m.rule.contains_display_name`**
|
||||
|
||||
Matches any message whose content is unencrypted and contains the user's
|
||||
current display name in the room in which it was sent.
|
||||
Matches any message whose content contains the user's current display name
|
||||
in the room in which it was sent.
|
||||
|
||||
Definition:
|
||||
|
||||
|
|
@ -524,6 +472,39 @@ Definition:
|
|||
}
|
||||
```
|
||||
|
||||
**`.m.rule.roomnotif`**
|
||||
|
||||
Matches any message from a sender with the proper power level whose content
|
||||
contains the text `@room`, signifying the whole room should be notified of
|
||||
the event.
|
||||
|
||||
Definition:
|
||||
|
||||
```json
|
||||
{
|
||||
"rule_id": ".m.rule.roomnotif",
|
||||
"default": true,
|
||||
"enabled": true,
|
||||
"conditions": [
|
||||
{
|
||||
"kind": "event_match",
|
||||
"key": "content.body",
|
||||
"pattern": "@room"
|
||||
},
|
||||
{
|
||||
"kind": "sender_notification_permission",
|
||||
"key": "room"
|
||||
}
|
||||
],
|
||||
"actions": [
|
||||
"notify",
|
||||
{
|
||||
"set_tweak": "highlight"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**<a name="mruletombstone"></a>`.m.rule.tombstone`**
|
||||
|
||||
Matches any state event whose type is `m.room.tombstone`. This is
|
||||
|
|
@ -587,44 +568,12 @@ Definition:
|
|||
}
|
||||
```
|
||||
|
||||
**`.m.rule.roomnotif`**
|
||||
|
||||
Matches any message whose content is unencrypted and contains the text
|
||||
`@room`, signifying the whole room should be notified of the event.
|
||||
|
||||
Definition:
|
||||
|
||||
```json
|
||||
{
|
||||
"rule_id": ".m.rule.roomnotif",
|
||||
"default": true,
|
||||
"enabled": true,
|
||||
"conditions": [
|
||||
{
|
||||
"kind": "event_match",
|
||||
"key": "content.body",
|
||||
"pattern": "@room"
|
||||
},
|
||||
{
|
||||
"kind": "sender_notification_permission",
|
||||
"key": "room"
|
||||
}
|
||||
],
|
||||
"actions": [
|
||||
"notify",
|
||||
{
|
||||
"set_tweak": "highlight"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
###### Default Content Rules
|
||||
##### Default Content Rules
|
||||
|
||||
**`.m.rule.contains_user_name`**
|
||||
|
||||
Matches any message whose content is unencrypted and contains the local
|
||||
part of the user's Matrix ID, separated by word boundaries.
|
||||
Matches any message whose content contains the local part of the user's
|
||||
Matrix ID, separated by word boundaries.
|
||||
|
||||
Definition (as a `content` rule):
|
||||
|
||||
|
|
@ -647,7 +596,7 @@ Definition (as a `content` rule):
|
|||
}
|
||||
```
|
||||
|
||||
###### Default Underride Rules
|
||||
##### Default Underride Rules
|
||||
|
||||
**`.m.rule.call`**
|
||||
|
||||
|
|
@ -796,14 +745,14 @@ Definition:
|
|||
}
|
||||
```
|
||||
|
||||
##### Push Rules: API
|
||||
#### Push Rules: API
|
||||
|
||||
Clients can retrieve, add, modify and remove push rules globally or
|
||||
per-device using the APIs below.
|
||||
|
||||
{{% http-api spec="client-server" api="pushrules" %}}
|
||||
|
||||
##### Push Rules: Events
|
||||
#### Push Rules: Events
|
||||
|
||||
When a user changes their push rules a `m.push_rules` event is sent to
|
||||
all clients in the `account_data` section of their next [`/sync`](#get_matrixclientv3sync) request.
|
||||
|
|
@ -811,7 +760,7 @@ The content of the event is the current push rules for the user.
|
|||
|
||||
{{% event event="m.push_rules" %}}
|
||||
|
||||
###### Examples
|
||||
##### Examples
|
||||
|
||||
To create a rule that suppresses notifications for the room with ID
|
||||
`!dj234r78wl45Gh4D:matrix.org`:
|
||||
|
|
@ -862,8 +811,76 @@ than the room, sender and content rules):
|
|||
]
|
||||
}'
|
||||
|
||||
|
||||
#### Client behaviour
|
||||
|
||||
Clients MUST configure a Pusher before they will receive push
|
||||
notifications. There is a single API endpoint for this, as described
|
||||
below.
|
||||
|
||||
{{% http-api spec="client-server" api="pusher" %}}
|
||||
|
||||
##### Listing Notifications
|
||||
|
||||
A client can retrieve a list of events that it has been notified about.
|
||||
This may be useful so that users can see a summary of what important
|
||||
messages they have received.
|
||||
|
||||
{{% http-api spec="client-server" api="notifications" %}}
|
||||
|
||||
##### Receiving notifications
|
||||
|
||||
Servers MUST include the number of unread notifications in a client's
|
||||
`/sync` stream, and MUST update it as it changes. Notifications are
|
||||
determined by the push rules which apply to an event.
|
||||
|
||||
For encrypted events, the homeserver has limited access to the event content
|
||||
and properly processing push rules falls on the client. Clients should process
|
||||
push rules for each incoming event *after decrypting* them. This may result in
|
||||
needing to modify the number of unread notifications received from the homeserver.
|
||||
|
||||
##### Marking notifications as read
|
||||
|
||||
When the user updates their read receipt (either by using the API or by
|
||||
sending an event), notifications prior to and including that event MUST
|
||||
be marked as read. Which specific events are affected can vary depending
|
||||
on whether a [threaded read receipt](#threaded-read-receipts) was used.
|
||||
Note that users can send both an `m.read` and `m.read.private` receipt,
|
||||
both of which are capable of clearing notifications.
|
||||
|
||||
If the user has both `m.read` and `m.read.private` set in the room then
|
||||
the receipt which is more recent/ahead must be used to determine where
|
||||
the user has read up to. For example, given an oldest-first set of events A,
|
||||
B, C, and D the `m.read` receipt could be at event C and `m.read.private`
|
||||
at event A - the user is considered to have read up to event C. If the
|
||||
`m.read.private` receipt is then updated to point to B or C, the user's
|
||||
notification state doesn't change (the `m.read` receipt is still more
|
||||
ahead), however if the `m.read.private` receipt were to be updated to
|
||||
event D then the user has read up to D (the `m.read` receipt is now
|
||||
behind the `m.read.private` receipt).
|
||||
|
||||
{{< added-in v="1.4" >}} When handling threaded read receipts, the server
|
||||
is to partition the notification count to each thread (with the main timeline
|
||||
being its own thread). To determine if an event is part of a thread the
|
||||
server follows the [event relationship](#forming-relationships-between-events)
|
||||
until it finds a thread root (as specified by the [threading module](#threading)),
|
||||
however it is not recommended that the server traverse infinitely. Instead,
|
||||
implementations are encouraged to do a maximum of 3 hops to find a thread
|
||||
before deciding that the event does not belong to a thread. This is primarily
|
||||
to ensure that future events, like `m.reaction`, are correctly considered
|
||||
"part of" a given thread.
|
||||
|
||||
#### Server behaviour
|
||||
|
||||
When receiving a new event homeservers process push rules for each of the local
|
||||
users in the room (excluding the sender). This may result in:
|
||||
|
||||
* Generating a new number of unread notifications for the user.
|
||||
* Making a request to the configured push gateway.
|
||||
|
||||
The updated notification count from a new event MUST appear in the same `/sync`
|
||||
response as the event itself.
|
||||
|
||||
#### Push Gateway behaviour
|
||||
|
||||
##### Recommendations for APNS
|
||||
|
|
|
|||
|
|
@ -1,5 +1,3 @@
|
|||
weight: 340
|
||||
|
||||
### Spaces
|
||||
|
||||
{{% added-in v="1.2" %}}
|
||||
|
|
|
|||
|
|
@ -1,12 +1,12 @@
|
|||
|
||||
### Third party invites
|
||||
### Third-party invites
|
||||
|
||||
This module adds in support for inviting new members to a room where
|
||||
their Matrix user ID is not known, instead addressing them by a third
|
||||
party identifier such as an email address. There are two flows here; one
|
||||
if a Matrix user ID is known for the third party identifier, and one if
|
||||
their Matrix user ID is not known, instead addressing them by a third-party
|
||||
identifier such as an email address. There are two flows here; one
|
||||
if a Matrix user ID is known for the third-party identifier, and one if
|
||||
not. Either way, the client calls `/invite` with the details of the
|
||||
third party identifier.
|
||||
third-party identifier.
|
||||
|
||||
The homeserver asks the identity server whether a Matrix user ID is
|
||||
known for that identifier:
|
||||
|
|
@ -22,7 +22,7 @@ When the invitee's homeserver receives the notification of the binding,
|
|||
it should insert an `m.room.member` event into the room's graph for that
|
||||
user, with `content.membership` = `invite`, as well as a
|
||||
`content.third_party_invite` property which contains proof that the
|
||||
invitee does indeed own that third party identifier. See the
|
||||
invitee does indeed own that third-party identifier. See the
|
||||
[m.room.member](#mroommember) schema for more information.
|
||||
|
||||
#### Events
|
||||
|
|
@ -31,14 +31,14 @@ invitee does indeed own that third party identifier. See the
|
|||
|
||||
#### Client behaviour
|
||||
|
||||
A client asks a server to invite a user by their third party identifier.
|
||||
A client asks a server to invite a user by their third-party identifier.
|
||||
|
||||
{{% http-api spec="client-server" api="third_party_membership" %}}
|
||||
|
||||
#### Server behaviour
|
||||
|
||||
Upon receipt of an `/invite`, the server is expected to look up the
|
||||
third party identifier with the provided identity server. If the lookup
|
||||
third-party identifier with the provided identity server. If the lookup
|
||||
yields a result for a Matrix User ID then the normal invite process can
|
||||
be initiated. This process ends up looking like this:
|
||||
|
||||
|
|
@ -104,12 +104,12 @@ looking like this:
|
|||
All homeservers MUST verify the signature in the event's
|
||||
`content.third_party_invite.signed` object.
|
||||
|
||||
The third party user will then need to verify their identity, which
|
||||
The third-party user will then need to verify their identity, which
|
||||
results in a call from the identity server to the homeserver that bound
|
||||
the third party identifier to a user. The homeserver then exchanges the
|
||||
the third-party identifier to a user. The homeserver then exchanges the
|
||||
`m.room.third_party_invite` event in the room for a complete
|
||||
`m.room.member` event for `membership: invite` for the user that has
|
||||
bound the third party identifier.
|
||||
bound the third-party identifier.
|
||||
|
||||
If a homeserver is joining a room for the first time because of an
|
||||
`m.room.third_party_invite`, the server which is already participating
|
||||
|
|
@ -123,7 +123,7 @@ view of the room. They may, however, indicate to their clients that a
|
|||
member's membership is questionable.
|
||||
|
||||
For example, given H1, H2, and H3 as homeservers, UserA as a user of H1,
|
||||
and an identity server IS, the full sequence for a third party invite
|
||||
and an identity server IS, the full sequence for a third-party invite
|
||||
would look like the following. This diagram assumes H1 and H2 are
|
||||
residents of the room while H3 is attempting to join.
|
||||
|
||||
|
|
@ -144,7 +144,7 @@ residents of the room while H3 is attempting to join.
|
|||
| | | POST /store-invite | | |
|
||||
| | |---------------------------------------------------------------------------------------------->|
|
||||
| | | | | |
|
||||
| | | | Token, keys, etc for third party invite |
|
||||
| | | | Token, keys, etc for third-party invite |
|
||||
| | |<----------------------------------------------------------------------------------------------|
|
||||
| | | | | |
|
||||
| | | (Federation) Emit m.room.third_party_invite | | |
|
||||
|
|
@ -214,13 +214,13 @@ still be performed, so the attack surface here is minimized.
|
|||
There are a number of privacy and trust implications to this module.
|
||||
|
||||
It is important for user privacy that leaking the mapping between a
|
||||
matrix user ID and a third party identifier is hard. In particular,
|
||||
being able to look up all third party identifiers from a matrix user ID
|
||||
(and accordingly, being able to link each third party identifier) should
|
||||
be avoided wherever possible. To this end, the third party identifier is
|
||||
matrix user ID and a third-party identifier is hard. In particular,
|
||||
being able to look up all third-party identifiers from a matrix user ID
|
||||
(and accordingly, being able to link each third-party identifier) should
|
||||
be avoided wherever possible. To this end, the third-party identifier is
|
||||
not put in any event, rather an opaque display name provided by the
|
||||
identity server is put into the events. Clients should not remember or
|
||||
display third party identifiers from invites, other than for the use of
|
||||
display third-party identifiers from invites, other than for the use of
|
||||
the inviter themself.
|
||||
|
||||
Homeservers are not required to trust any particular identity server(s).
|
||||
|
|
|
|||
|
|
@ -1,18 +1,18 @@
|
|||
|
||||
### Third Party Networks
|
||||
### Third-party Networks
|
||||
|
||||
Application services can provide access to third party networks via
|
||||
Application services can provide access to third-party networks via
|
||||
bridging. This allows Matrix users to communicate with users on other
|
||||
communication platforms, with messages ferried back and forth by the
|
||||
application service. A single application service may bridge multiple
|
||||
third party networks, and many individual locations within those
|
||||
networks. A single third party network location may be bridged to
|
||||
third-party networks, and many individual locations within those
|
||||
networks. A single third-party network location may be bridged to
|
||||
multiple Matrix rooms.
|
||||
|
||||
#### Third Party Lookups
|
||||
#### Third-party Lookups
|
||||
|
||||
A client may wish to provide a rich interface for joining third party
|
||||
locations and connecting with third party users. Information necessary
|
||||
for such an interface is provided by third party lookups.
|
||||
A client may wish to provide a rich interface for joining third-party
|
||||
locations and connecting with third-party users. Information necessary
|
||||
for such an interface is provided by third-party lookups.
|
||||
|
||||
{{% http-api spec="client-server" api="third_party_lookup" %}}
|
||||
|
|
|
|||
|
|
@ -76,7 +76,7 @@ Clients which understand how to work with threads should simply do so, however c
|
|||
might not be aware of threads (due to age or scope) might not be able to helpfully represent
|
||||
the conversation history to its users.
|
||||
|
||||
To work around this, events sent by clients which understand threads include [rich reply](#rich-replies)
|
||||
To work around this, events sent by clients which understand threads SHOULD include [rich reply](#rich-replies)
|
||||
metadata to attempt to form a reply chain representation of the conversation. This representation
|
||||
is not ideal for heavily threaded rooms, but allows for users to have context as to what is
|
||||
being discussed with respect to other messages in the room.
|
||||
|
|
|
|||
|
|
@ -98,11 +98,11 @@ There was an error sending an email. Typically seen when attempting to
|
|||
verify ownership of a given email address.
|
||||
|
||||
`M_INVALID_ADDRESS`
|
||||
The provided third party address was not valid.
|
||||
The provided third-party address was not valid.
|
||||
|
||||
`M_SEND_ERROR`
|
||||
There was an error sending a notification. Typically seen when
|
||||
attempting to verify ownership of a given third party address.
|
||||
attempting to verify ownership of a given third-party address.
|
||||
|
||||
`M_UNRECOGNIZED`
|
||||
The request contained an unrecognised value, such as an unknown token or
|
||||
|
|
@ -114,9 +114,9 @@ not implemented or a 405 HTTP status code if the endpoint is implemented, but
|
|||
the incorrect HTTP method is used.
|
||||
|
||||
`M_THREEPID_IN_USE`
|
||||
The third party identifier is already in use by another user. Typically
|
||||
The third-party identifier is already in use by another user. Typically
|
||||
this error will have an additional `mxid` property to indicate who owns
|
||||
the third party identifier.
|
||||
the third-party identifier.
|
||||
|
||||
`M_UNKNOWN`
|
||||
An unknown error has occurred.
|
||||
|
|
@ -369,7 +369,7 @@ To start a session, the client makes a request to the appropriate
|
|||
token to the user, and the user provides the token to the client. The
|
||||
client then provides the token to the appropriate `/submitToken`
|
||||
endpoint, completing the session. At this point, the client should
|
||||
`/bind` the third party identifier or leave it for another entity to
|
||||
`/bind` the third-party identifier or leave it for another entity to
|
||||
bind.
|
||||
|
||||
### Format of a validation token
|
||||
|
|
|
|||
|
|
@ -86,7 +86,7 @@ split-brain situation due to not understanding the new rules.
|
|||
|
||||
A room version is defined as a string of characters which MUST NOT
|
||||
exceed 32 codepoints in length. Room versions MUST NOT be empty and
|
||||
SHOULD contain only the characters `a-z`, `0-9`, `.`, and `-`.
|
||||
MUST contain only the characters `a-z`, `0-9`, `.`, and `-`.
|
||||
|
||||
Room versions are not intended to be parsed and should be treated as
|
||||
opaque identifiers. Room versions consisting only of the characters
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ signatures in HTTP Authorization headers at the HTTP layer.
|
|||
There are three main kinds of communication that occur between
|
||||
homeservers:
|
||||
|
||||
Persisted Data Units (PDUs):
|
||||
Persistent Data Units (PDUs):
|
||||
These events are broadcast from one homeserver to any others that have
|
||||
joined the same room (identified by Room ID). They are persisted in
|
||||
long-term storage and record the history of messages and state for a
|
||||
|
|
@ -350,7 +350,7 @@ The authorization parameters to include are:
|
|||
- `origin`: the server name of the sending server. This is the same as the
|
||||
`origin` field from JSON described in step 1.
|
||||
- `destination`: {{< added-in v="1.3" >}} the server name of the receiving
|
||||
sender. This is the same as the `destination` field from the JSON described
|
||||
server. This is the same as the `destination` field from the JSON described
|
||||
in step 1. For compatibility with older servers, recipients should accept
|
||||
requests without this parameter, but MUST always send it. If this property
|
||||
is included, but the value does not match the receiving server's name, the
|
||||
|
|
@ -877,7 +877,8 @@ on the resulting `m.room.member` event.
|
|||
If the joining server fails all conditions then a 403 `M_FORBIDDEN` error
|
||||
is used by the resident server.
|
||||
|
||||
## <a name="knocking-rooms"> Knocking upon a room
|
||||
<a name="knocking-rooms">
|
||||
## Knocking upon a room
|
||||
|
||||
Rooms can permit knocking through the join rules, and if permitted this
|
||||
gives users a way to request to join (be invited) to the room. Users who
|
||||
|
|
@ -937,9 +938,9 @@ the event to other servers in the room.
|
|||
## Third-party invites
|
||||
|
||||
{{% boxes/note %}}
|
||||
More information about third party invites is available in the
|
||||
More information about third-party invites is available in the
|
||||
[Client-Server API](/client-server-api) under
|
||||
the Third Party Invites module.
|
||||
the Third-party Invites module.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
When a user wants to invite another user in a room but doesn't know the
|
||||
|
|
@ -1075,7 +1076,7 @@ more specific queries that can be made.
|
|||
|
||||
## OpenID
|
||||
|
||||
Third party services can exchange an access token previously generated
|
||||
Third-party services can exchange an access token previously generated
|
||||
by the <span class="title-ref">Client-Server API</span> for information
|
||||
about a user. This can help verify that a user is who they say they are
|
||||
without granting full access to the user's account.
|
||||
|
|
|
|||
|
|
@ -17,11 +17,11 @@ properties:
|
|||
type: string
|
||||
example: "#freenode_#matrix:matrix.org"
|
||||
protocol:
|
||||
description: The protocol ID that the third party location is a part of.
|
||||
description: The protocol ID that the third-party location is a part of.
|
||||
type: string
|
||||
example: "irc"
|
||||
fields:
|
||||
description: Information used to identify this third party location.
|
||||
description: Information used to identify this third-party location.
|
||||
type: object
|
||||
example: {
|
||||
"network": "freenode",
|
||||
|
|
|
|||
|
|
@ -12,6 +12,6 @@
|
|||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
type: array
|
||||
description: List of matched third party locations.
|
||||
description: List of matched third-party locations.
|
||||
items:
|
||||
$ref: location.yaml
|
||||
|
|
|
|||
|
|
@ -16,28 +16,28 @@ type: object
|
|||
properties:
|
||||
user_fields:
|
||||
description: |-
|
||||
Fields which may be used to identify a third party user. These should be
|
||||
Fields which may be used to identify a third-party user. These should be
|
||||
ordered to suggest the way that entities may be grouped, where higher
|
||||
groupings are ordered first. For example, the name of a network should be
|
||||
searched before the nickname of a user.
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: Field used to identify a third party user.
|
||||
description: Field used to identify a third-party user.
|
||||
example: ["network", "nickname"]
|
||||
location_fields:
|
||||
description: |-
|
||||
Fields which may be used to identify a third party location. These should be
|
||||
Fields which may be used to identify a third-party location. These should be
|
||||
ordered to suggest the way that entities may be grouped, where higher
|
||||
groupings are ordered first. For example, the name of a network should be
|
||||
searched before the name of a channel.
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: Field used to identify a third party location.
|
||||
description: Field used to identify a third-party location.
|
||||
example: ["network", "channel"]
|
||||
icon:
|
||||
description: A content URI representing an icon for the third party protocol.
|
||||
description: A content URI representing an icon for the third-party protocol.
|
||||
type: string
|
||||
example: "mxc://example.org/aBcDeFgH"
|
||||
field_types:
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@
|
|||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
type: object
|
||||
description: Dictionary of supported third party protocols.
|
||||
description: Dictionary of supported third-party protocols.
|
||||
additionalProperties:
|
||||
$ref: protocol.yaml
|
||||
example: {
|
||||
|
|
|
|||
|
|
@ -15,15 +15,15 @@
|
|||
# TODO: Change userid to user_id as a breaking change
|
||||
properties:
|
||||
userid:
|
||||
description: A Matrix User ID represting a third party user.
|
||||
description: A Matrix User ID represting a third-party user.
|
||||
type: string
|
||||
example: "@_gitter_jim:matrix.org"
|
||||
protocol:
|
||||
description: The protocol ID that the third party location is a part of.
|
||||
description: The protocol ID that the third-party location is a part of.
|
||||
type: string
|
||||
example: "gitter"
|
||||
fields:
|
||||
description: Information used to identify this third party location.
|
||||
description: Information used to identify this third-party location.
|
||||
type: object
|
||||
example: {
|
||||
"user": "jim"
|
||||
|
|
|
|||
|
|
@ -12,6 +12,6 @@
|
|||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
type: array
|
||||
description: List of matched third party users.
|
||||
description: List of matched third-party users.
|
||||
items:
|
||||
$ref: user.yaml
|
||||
|
|
|
|||
|
|
@ -32,7 +32,7 @@ paths:
|
|||
summary: Retrieve metadata about a specific protocol that the application service supports.
|
||||
description: |-
|
||||
This API is called by the homeserver when it wants to present clients
|
||||
with specific information about the various third party networks that
|
||||
with specific information about the various third-party networks that
|
||||
an application service supports.
|
||||
operationId: getProtocolMetadata
|
||||
security:
|
||||
|
|
@ -78,10 +78,10 @@ paths:
|
|||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
"/thirdparty/user/{protocol}":
|
||||
get:
|
||||
summary: Retrieve the Matrix User ID of a corresponding third party user.
|
||||
summary: Retrieve the Matrix User ID of a corresponding third-party user.
|
||||
description: |-
|
||||
This API is called by the homeserver in order to retrieve a Matrix
|
||||
User ID linked to a user on the third party network, given a set of
|
||||
User ID linked to a user on the third-party network, given a set of
|
||||
user parameters.
|
||||
operationId: queryUserByProtocol
|
||||
security:
|
||||
|
|
@ -133,9 +133,9 @@ paths:
|
|||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
"/thirdparty/location/{protocol}":
|
||||
get:
|
||||
summary: Retrieve Matrix-side portal rooms leading to a third party location.
|
||||
summary: Retrieve Matrix-side portal rooms leading to a third-party location.
|
||||
description: |-
|
||||
Retrieve a list of Matrix portal rooms that lead to the matched third party location.
|
||||
Retrieve a list of Matrix portal rooms that lead to the matched third-party location.
|
||||
operationId: queryLocationByProtocol
|
||||
security:
|
||||
- homeserverAccessToken: []
|
||||
|
|
@ -151,7 +151,7 @@ paths:
|
|||
type: string
|
||||
description: |-
|
||||
One or more custom fields that are passed to the application
|
||||
service to help identify the third party location.
|
||||
service to help identify the third-party location.
|
||||
responses:
|
||||
200:
|
||||
description: At least one portal room was found.
|
||||
|
|
@ -186,9 +186,9 @@ paths:
|
|||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
"/thirdparty/location":
|
||||
get:
|
||||
summary: Reverse-lookup third party locations given a Matrix room alias.
|
||||
summary: Reverse-lookup third-party locations given a Matrix room alias.
|
||||
description: |-
|
||||
Retrieve an array of third party network locations from a Matrix room
|
||||
Retrieve an array of third-party network locations from a Matrix room
|
||||
alias.
|
||||
operationId: queryLocationByAlias
|
||||
security:
|
||||
|
|
@ -201,7 +201,7 @@ paths:
|
|||
responses:
|
||||
200:
|
||||
description: |-
|
||||
All found third party locations.
|
||||
All found third-party locations.
|
||||
schema:
|
||||
$ref: definitions/location_batch.yaml
|
||||
401:
|
||||
|
|
@ -233,9 +233,9 @@ paths:
|
|||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
"/thirdparty/user":
|
||||
get:
|
||||
summary: Reverse-lookup third party users given a Matrix User ID.
|
||||
summary: Reverse-lookup third-party users given a Matrix User ID.
|
||||
description: |-
|
||||
Retrieve an array of third party users from a Matrix User ID.
|
||||
Retrieve an array of third-party users from a Matrix User ID.
|
||||
operationId: queryUserByID
|
||||
security:
|
||||
- homeserverAccessToken: []
|
||||
|
|
@ -247,7 +247,7 @@ paths:
|
|||
responses:
|
||||
200:
|
||||
description: |-
|
||||
An array of third party users.
|
||||
An array of third-party users.
|
||||
schema:
|
||||
$ref: definitions/user_batch.yaml
|
||||
401:
|
||||
|
|
|
|||
|
|
@ -30,12 +30,12 @@ securityDefinitions:
|
|||
paths:
|
||||
"/account/3pid":
|
||||
get:
|
||||
summary: Gets a list of a user's third party identifiers.
|
||||
summary: Gets a list of a user's third-party identifiers.
|
||||
description: |-
|
||||
Gets a list of the third party identifiers that the homeserver has
|
||||
Gets a list of the third-party identifiers that the homeserver has
|
||||
associated with the user's account.
|
||||
|
||||
This is *not* the same as the list of third party identifiers bound to
|
||||
This is *not* the same as the list of third-party identifiers bound to
|
||||
the user's Matrix ID in identity servers.
|
||||
|
||||
Identifiers in this list may be used by the homeserver as, for example,
|
||||
|
|
@ -64,15 +64,15 @@ paths:
|
|||
type: array
|
||||
items:
|
||||
type: object
|
||||
title: Third party identifier
|
||||
title: Third-party identifier
|
||||
properties:
|
||||
medium:
|
||||
type: string
|
||||
description: The medium of the third party identifier.
|
||||
description: The medium of the third-party identifier.
|
||||
enum: ["email", "msisdn"]
|
||||
address:
|
||||
type: string
|
||||
description: The third party identifier address.
|
||||
description: The third-party identifier address.
|
||||
validated_at:
|
||||
type: integer
|
||||
format: int64
|
||||
|
|
@ -84,7 +84,7 @@ paths:
|
|||
format: int64
|
||||
description:
|
||||
The timestamp, in milliseconds, when the homeserver
|
||||
associated the third party identifier with the user.
|
||||
associated the third-party identifier with the user.
|
||||
required: ['medium', 'address', 'validated_at', 'added_at']
|
||||
tags:
|
||||
- Account management
|
||||
|
|
@ -115,7 +115,7 @@ paths:
|
|||
three_pid_creds:
|
||||
title: "ThreePidCredentials"
|
||||
type: object
|
||||
description: The third party credentials to associate with the account.
|
||||
description: The third-party credentials to associate with the account.
|
||||
properties:
|
||||
client_secret:
|
||||
type: string
|
||||
|
|
@ -174,7 +174,7 @@ paths:
|
|||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_THREEPID_AUTH_FAILED",
|
||||
"error": "The third party credentials could not be verified by the identity server."
|
||||
"error": "The third-party credentials could not be verified by the identity server."
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
|
|
@ -290,9 +290,9 @@ paths:
|
|||
- Account management
|
||||
"/account/3pid/delete":
|
||||
post:
|
||||
summary: Deletes a third party identifier from the user's account
|
||||
summary: Deletes a third-party identifier from the user's account
|
||||
description: |-
|
||||
Removes a third party identifier from the user's account. This might not
|
||||
Removes a third-party identifier from the user's account. This might not
|
||||
cause an unbind of the identifier from the identity server.
|
||||
|
||||
Unlike other endpoints, this endpoint does not take an `id_access_token`
|
||||
|
|
@ -318,18 +318,18 @@ paths:
|
|||
example: "example.org"
|
||||
medium:
|
||||
type: string
|
||||
description: The medium of the third party identifier being removed.
|
||||
description: The medium of the third-party identifier being removed.
|
||||
enum: ["email", "msisdn"]
|
||||
example: "email"
|
||||
address:
|
||||
type: string
|
||||
description: The third party address being removed.
|
||||
description: The third-party address being removed.
|
||||
example: "example@example.org"
|
||||
required: ['medium', 'address']
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
The homeserver has disassociated the third party identifier from the
|
||||
The homeserver has disassociated the third-party identifier from the
|
||||
user.
|
||||
schema:
|
||||
type: object
|
||||
|
|
@ -355,9 +355,9 @@ paths:
|
|||
- Account management
|
||||
"/account/3pid/unbind":
|
||||
post:
|
||||
summary: Removes a user's third party identifier from an identity server.
|
||||
summary: Removes a user's third-party identifier from an identity server.
|
||||
description: |-
|
||||
Removes a user's third party identifier from the provided identity server
|
||||
Removes a user's third-party identifier from the provided identity server
|
||||
without removing it from the homeserver.
|
||||
|
||||
Unlike other endpoints, this endpoint does not take an `id_access_token`
|
||||
|
|
@ -383,18 +383,18 @@ paths:
|
|||
example: "example.org"
|
||||
medium:
|
||||
type: string
|
||||
description: The medium of the third party identifier being removed.
|
||||
description: The medium of the third-party identifier being removed.
|
||||
enum: ["email", "msisdn"]
|
||||
example: "email"
|
||||
address:
|
||||
type: string
|
||||
description: The third party address being removed.
|
||||
description: The third-party address being removed.
|
||||
example: "example@example.org"
|
||||
required: ['medium', 'address']
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
The identity server has disassociated the third party identifier from the
|
||||
The identity server has disassociated the third-party identifier from the
|
||||
user.
|
||||
schema:
|
||||
type: object
|
||||
|
|
@ -446,18 +446,18 @@ paths:
|
|||
$ref: "definitions/request_token_response.yaml"
|
||||
403:
|
||||
description: |-
|
||||
The homeserver does not allow the third party identifier as a
|
||||
The homeserver does not allow the third-party identifier as a
|
||||
contact option.
|
||||
schema:
|
||||
$ref: "definitions/errors/error.yaml"
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_THREEPID_DENIED",
|
||||
"error": "Third party identifier is not allowed"
|
||||
"error": "Third-party identifier is not allowed"
|
||||
}
|
||||
400:
|
||||
description: |-
|
||||
The third party identifier is already in use on the homeserver, or
|
||||
The third-party identifier is already in use on the homeserver, or
|
||||
the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
|
||||
can be returned if the server does not trust/support the identity server
|
||||
provided in the request.
|
||||
|
|
@ -466,7 +466,7 @@ paths:
|
|||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_THREEPID_IN_USE",
|
||||
"error": "Third party identifier already in use"
|
||||
"error": "Third-party identifier already in use"
|
||||
}
|
||||
tags:
|
||||
- Account management
|
||||
|
|
@ -496,18 +496,18 @@ paths:
|
|||
$ref: "definitions/request_token_response.yaml"
|
||||
403:
|
||||
description: |-
|
||||
The homeserver does not allow the third party identifier as a
|
||||
The homeserver does not allow the third-party identifier as a
|
||||
contact option.
|
||||
schema:
|
||||
$ref: "definitions/errors/error.yaml"
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_THREEPID_DENIED",
|
||||
"error": "Third party identifier is not allowed"
|
||||
"error": "Third-party identifier is not allowed"
|
||||
}
|
||||
400:
|
||||
description: |-
|
||||
The third party identifier is already in use on the homeserver, or
|
||||
The third-party identifier is already in use on the homeserver, or
|
||||
the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
|
||||
can be returned if the server does not trust/support the identity server
|
||||
provided in the request.
|
||||
|
|
@ -516,7 +516,7 @@ paths:
|
|||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_THREEPID_IN_USE",
|
||||
"error": "Third party identifier already in use"
|
||||
"error": "Third-party identifier already in use"
|
||||
}
|
||||
tags:
|
||||
- Account management
|
||||
|
|
|
|||
|
|
@ -138,7 +138,7 @@ paths:
|
|||
invite_3pid:
|
||||
type: array
|
||||
description: |-
|
||||
A list of objects representing third party IDs to invite into
|
||||
A list of objects representing third-party IDs to invite into
|
||||
the room.
|
||||
items:
|
||||
type: object
|
||||
|
|
@ -146,7 +146,7 @@ paths:
|
|||
properties:
|
||||
id_server:
|
||||
type: string
|
||||
description: The hostname+port of the identity server which should be used for third party identifier lookups.
|
||||
description: The hostname+port of the identity server which should be used for third-party identifier lookups.
|
||||
id_access_token:
|
||||
type: string
|
||||
description: |-
|
||||
|
|
@ -160,7 +160,7 @@ paths:
|
|||
(see [the list of recognised values](/appendices/#3pid-types)).
|
||||
address:
|
||||
type: string
|
||||
description: The invitee's third party identifier.
|
||||
description: The invitee's third-party identifier.
|
||||
required: ["id_server", "id_access_token", "medium", "address"]
|
||||
room_version:
|
||||
type: string
|
||||
|
|
|
|||
|
|
@ -35,6 +35,8 @@ properties:
|
|||
The public key. The object must have exactly one property, whose name is
|
||||
in the form `<algorithm>:<unpadded_base64_public_key>`, and whose value
|
||||
is the unpadded base64 public key.
|
||||
minProperties: 1
|
||||
maxProperties: 1
|
||||
example:
|
||||
"ed25519:alice+base64+public+key": "alice+base64+public+key"
|
||||
signatures:
|
||||
|
|
|
|||
|
|
@ -11,23 +11,24 @@
|
|||
# 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.
|
||||
$ref: error.yaml
|
||||
type: object
|
||||
title: RateLimitError
|
||||
description: The rate limit was reached for this request
|
||||
properties:
|
||||
errcode:
|
||||
type: string
|
||||
description: The M_LIMIT_EXCEEDED error code
|
||||
example: M_LIMIT_EXCEEDED
|
||||
error:
|
||||
type: string
|
||||
description: A human-readable error message.
|
||||
example: Too many requests
|
||||
retry_after_ms:
|
||||
type: integer
|
||||
description: |-
|
||||
The amount of time in milliseconds the client should wait
|
||||
before trying the request again.
|
||||
example: 2000
|
||||
required: ["errcode"]
|
||||
allOf:
|
||||
- $ref: error.yaml
|
||||
- type: object
|
||||
title: RateLimitError
|
||||
description: The rate limit was reached for this request
|
||||
properties:
|
||||
errcode:
|
||||
type: string
|
||||
description: The M_LIMIT_EXCEEDED error code
|
||||
example: M_LIMIT_EXCEEDED
|
||||
error:
|
||||
type: string
|
||||
description: A human-readable error message.
|
||||
example: Too many requests
|
||||
retry_after_ms:
|
||||
type: integer
|
||||
description: |-
|
||||
The amount of time in milliseconds the client should wait
|
||||
before trying the request again.
|
||||
example: 2000
|
||||
required: ["errcode"]
|
||||
|
|
|
|||
|
|
@ -16,9 +16,7 @@ properties:
|
|||
events:
|
||||
description: List of events.
|
||||
items:
|
||||
allOf:
|
||||
- $ref: ../../../event-schemas/schema/core-event-schema/event.yaml
|
||||
type: object
|
||||
$ref: ../../../event-schemas/schema/core-event-schema/event.yaml
|
||||
type: array
|
||||
type: object
|
||||
title: EventBatch
|
||||
|
|
|
|||
|
|
@ -14,7 +14,11 @@
|
|||
title: EventFilter
|
||||
properties:
|
||||
limit:
|
||||
description: The maximum number of events to return.
|
||||
description: |
|
||||
The maximum number of events to return, must be an integer greater than 0.
|
||||
|
||||
Servers should apply a default value, and impose a maximum value to avoid
|
||||
resource exhaustion.
|
||||
type: integer
|
||||
not_senders:
|
||||
description: A list of sender IDs to exclude. If this list is absent then no senders
|
||||
|
|
|
|||
|
|
@ -34,8 +34,8 @@ properties:
|
|||
pattern:
|
||||
type: string
|
||||
description: |-
|
||||
Required for `event_match` conditions. The glob-style pattern to
|
||||
match against.
|
||||
Required for `event_match` conditions. The [glob-style pattern](/appendices#glob-style-matching)
|
||||
to match against.
|
||||
is:
|
||||
type: string
|
||||
description: |-
|
||||
|
|
|
|||
|
|
@ -38,8 +38,7 @@ properties:
|
|||
conditions:
|
||||
type: array
|
||||
items:
|
||||
allOf:
|
||||
- $ref: push_condition.yaml
|
||||
$ref: push_condition.yaml
|
||||
description: |-
|
||||
The conditions that must hold true for an event in order for a rule to be
|
||||
applied to an event. A rule with no conditions always matches. Only
|
||||
|
|
@ -47,8 +46,8 @@ properties:
|
|||
pattern:
|
||||
type: string
|
||||
description: |-
|
||||
The glob-style pattern to match against. Only applicable to `content`
|
||||
rules.
|
||||
The [glob-style pattern](/appendices#glob-style-matching) to match against.
|
||||
Only applicable to `content` rules.
|
||||
required:
|
||||
- actions
|
||||
- default
|
||||
|
|
|
|||
|
|
@ -12,10 +12,10 @@
|
|||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
type: object
|
||||
title: Third Party Signed
|
||||
title: Third-party Signed
|
||||
description: |-
|
||||
A signature of an `m.third_party_invite` token to prove that this user
|
||||
owns a third party identity which has been invited to the room.
|
||||
owns a third-party identity which has been invited to the room.
|
||||
properties:
|
||||
sender:
|
||||
type: string
|
||||
|
|
|
|||
|
|
@ -36,7 +36,7 @@ paths:
|
|||
*Note that there are two forms of this API, which are documented separately.
|
||||
This version of the API requires that the inviter knows the Matrix
|
||||
identifier of the invitee. The other is documented in the
|
||||
[third party invites](/client-server-api/#third-party-invites) section.*
|
||||
[third-party invites](/client-server-api/#third-party-invites) section.*
|
||||
|
||||
This API invites a user to participate in a particular room.
|
||||
They do not start participating in the room until they actually join the
|
||||
|
|
|
|||
|
|
@ -219,7 +219,7 @@ paths:
|
|||
third_party_instance_id:
|
||||
type: string
|
||||
description: |-
|
||||
The specific third party network/protocol to request from the
|
||||
The specific third-party network/protocol to request from the
|
||||
homeserver. Can only be used if `include_all_networks` is false.
|
||||
example: "irc"
|
||||
example: {
|
||||
|
|
|
|||
|
|
@ -107,10 +107,10 @@ paths:
|
|||
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
|
||||
description: When logging in using a third party identifier, the medium of the identifier. Must be 'email'. Deprecated in favour of `identifier`.
|
||||
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
|
||||
description: Third party identifier for the user. Deprecated in favour of `identifier`.
|
||||
description: Third-party identifier for the user. Deprecated in favour of `identifier`.
|
||||
password:
|
||||
type: string
|
||||
description: |-
|
||||
|
|
|
|||
|
|
@ -109,10 +109,10 @@ paths:
|
|||
- object
|
||||
- string
|
||||
event:
|
||||
type: object
|
||||
title: Event
|
||||
description: The Event object for the event that triggered the notification.
|
||||
"$ref": "definitions/client_event_without_room_id.yaml"
|
||||
allOf:
|
||||
- "$ref": "definitions/client_event_without_room_id.yaml"
|
||||
profile_tag:
|
||||
type: string
|
||||
description: The profile tag of the rule that matched this event.
|
||||
|
|
|
|||
|
|
@ -221,7 +221,8 @@ paths:
|
|||
type: object
|
||||
title: "InviteEvent"
|
||||
description: "The invite event if `membership` is `invite`"
|
||||
$ref: "definitions/client_event.yaml"
|
||||
allOf:
|
||||
- $ref: "definitions/client_event.yaml"
|
||||
messages:
|
||||
type: object
|
||||
title: PaginationChunk
|
||||
|
|
|
|||
Some files were not shown because too many files have changed in this diff Show more
Loading…
Reference in a new issue