Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-04-09 12:54:10 +02:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'upstream/main' into msc4335

Browse source
This commit is contained in:
Hugh Nimmo-Smith 2026-03-04 10:19:33 +00:00
parent 9726841e01 2baca03e6b
commit 0445ab222e
51 changed files with 516 additions and 495 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
changelogs/client_server/newsfragments/2301.feature Normal file
View file

@ -0,0 +1 @@
Add recommendation about excluding non-cross-signed devices from encrypted conversations, as per [MSC4153](https://github.com/matrix-org/matrix-spec-proposals/pull/4153).

1
changelogs/client_server/newsfragments/2306.clarification Normal file
View file

@ -0,0 +1 @@
Clarify terminology for keys in cross-signing module.

1
changelogs/client_server/newsfragments/2311.feature Normal file
View file

@ -0,0 +1 @@
`/_matrix/client/v3/rooms/{roomId}/report` and `/_matrix/client/v3/rooms/{roomId}/report/{eventId}` may respond with HTTP 200 regardless of the reported subject's existence or add a random delay when generating responses as per [MSC4277](https://github.com/matrix-org/matrix-spec-proposals/pull/4277).

1
changelogs/client_server/newsfragments/2311.removal Normal file
View file

@ -0,0 +1 @@
The `score` request parameter on `/_matrix/client/v3/rooms/{roomId}/report/{eventId}` was removed as per [MSC4277](https://github.com/matrix-org/matrix-spec-proposals/pull/4277).

1
changelogs/client_server/newsfragments/2316.clarification Normal file
View file

@ -0,0 +1 @@
Add 404 responses to the OpenAPI of `GET /login` and `GET /auth_metadata` endpoints. The responses were already defined in text but not written in OpenAPI.

1
changelogs/client_server/newsfragments/2318.clarification Normal file
View file

@ -0,0 +1 @@
Fix various typos throughout the specification. Contributed by @HarHarLinks.

1
changelogs/internal/newsfragments/2317.clarification Normal file
View file

@ -0,0 +1 @@
Update the footer social links to match matrix.org. Contributed by @HarHarLinks.

1
changelogs/internal/newsfragments/2318.clarification Normal file
View file

@ -0,0 +1 @@
Fix various typos throughout the specification. Contributed by @HarHarLinks.

1
changelogs/internal/newsfragments/2323.clarification Normal file
View file

@ -0,0 +1 @@
Render error code sections as definition lists to improve readability.

1
changelogs/room_versions/newsfragments/2297.clarification Normal file
View file

@ -0,0 +1 @@
Clarify meaning of floating-point powerlevels.

1
changelogs/server_server/newsfragments/2284.clarification Normal file
View file

@ -0,0 +1 @@
Specify validation for PDUs passed to and returned from federation membership endpoints.

1
changelogs/server_server/newsfragments/2319.removal Normal file
View file

@ -0,0 +1 @@
Remove `/v1/send_join` and `/v1/send_leave`, as per [MSC4376](https://github.com/matrix-org/matrix-spec-proposals/pull/4376).

22
config/_default/hugo.toml
View file

@ -65,7 +65,7 @@ description = "Home of the Matrix specification for decentralised communication"
# Everything below this are Site Params # Everything below this are Site Params
[params] [params]
copyright = "The Matrix.org Foundation CIC" copyright = "The Matrix.org Foundation C.I.C."
[params.version] [params.version]
# must be one of "unstable", "current", "historical" # must be one of "unstable", "current", "historical"
@ -115,11 +115,6 @@ sidebar_menu_compact = true
url = "https://gitlab.matrix.org/matrix-org" url = "https://gitlab.matrix.org/matrix-org"
icon = "fab fa-gitlab" icon = "fab fa-gitlab"
desc = "Matrix on GitLab" desc = "Matrix on GitLab"
[[params.links.bottom]]
name = "YouTube"
url = "https://www.youtube.com/channel/UCVFkW-chclhuyYRbmmfwt6w"
icon = "fab fa-youtube"
desc = "Matrix YouTube channel"
[[params.links.bottom]] [[params.links.bottom]]
name = "Mastodon" name = "Mastodon"
url = "https://mastodon.matrix.org/@matrix" url = "https://mastodon.matrix.org/@matrix"
@ -130,6 +125,21 @@ sidebar_menu_compact = true
url = "https://bsky.app/profile/matrix.org" url = "https://bsky.app/profile/matrix.org"
icon = "fab fa-bluesky" icon = "fab fa-bluesky"
desc = "Matrix on Bluesky" desc = "Matrix on Bluesky"
[[params.links.bottom]]
name = "LinkedIn"
url = "https://www.linkedin.com/company/matrix-org/"
icon = "fab fa-linkedin"
desc = "Matrix on LinkedIn"
[[params.links.bottom]]
name = "YouTube"
url = "https://www.youtube.com/channel/UCVFkW-chclhuyYRbmmfwt6w"
icon = "fab fa-youtube"
desc = "Matrix YouTube channel"
[[params.links.bottom]]
name = "Matrix.org Blog Feed"
url = "https://matrix.org/atom.xml"
icon = "fas fa-rss"
desc = "Matrix.org Blog Atom Feed"
# configuration for the hugo development server # configuration for the hugo development server

80
content/client-server-api/_index.md
View file

@ -94,50 +94,50 @@ request being made was invalid.
These error codes can be returned by any API endpoint: These error codes can be returned by any API endpoint:
`M_FORBIDDEN` `M_FORBIDDEN`
Forbidden access, e.g. joining a room without permission, failed login. : Forbidden access, e.g. joining a room without permission, failed login.
`M_UNKNOWN_TOKEN` `M_UNKNOWN_TOKEN`
The access or refresh token specified was not recognised. : The access or refresh token specified was not recognised.
An additional response parameter, `soft_logout`, might be present on the : An additional response parameter, `soft_logout`, might be present on the
response for 401 HTTP status codes. See [the soft logout response for 401 HTTP status codes. See [the soft logout
section](#soft-logout) for more information. section](#soft-logout) for more information.
`M_MISSING_TOKEN` `M_MISSING_TOKEN`
No access token was specified for the request. : No access token was specified for the request.
`M_USER_LOCKED` `M_USER_LOCKED`
The account has been [locked](#account-locking) and cannot be used at this time. : The account has been [locked](#account-locking) and cannot be used at this time.
`M_USER_SUSPENDED` `M_USER_SUSPENDED`
The account has been [suspended](#account-suspension) and can only be used for : The account has been [suspended](#account-suspension) and can only be used for
limited actions at this time. limited actions at this time.
`M_BAD_JSON` `M_BAD_JSON`
Request contained valid JSON, but it was malformed in some way, e.g. : Request contained valid JSON, but it was malformed in some way, e.g.
missing required keys, invalid values for keys. missing required keys, invalid values for keys.
`M_NOT_JSON` `M_NOT_JSON`
Request did not contain valid JSON. : Request did not contain valid JSON.
`M_NOT_FOUND` `M_NOT_FOUND`
No resource was found for this request. : No resource was found for this request.
`M_LIMIT_EXCEEDED` `M_LIMIT_EXCEEDED`
Too many requests have been sent in a short period of time. Wait a while : Too many requests have been sent in a short period of time. Wait a while
then try again. See [Rate limiting](#rate-limiting). then try again. See [Rate limiting](#rate-limiting).
`M_UNRECOGNIZED` `M_UNRECOGNIZED`
The server did not understand the request. This is expected to be returned with : The server did not understand the request. This is expected to be returned with
a 404 HTTP status code if the endpoint is not implemented or a 405 HTTP status a 404 HTTP status code if the endpoint is not implemented or a 405 HTTP status
code if the endpoint is implemented, but the incorrect HTTP method is used. code if the endpoint is implemented, but the incorrect HTTP method is used.
`M_UNKNOWN_DEVICE` `M_UNKNOWN_DEVICE`
{{% added-in v="1.17" %}} The device ID supplied by the application service does : {{% added-in v="1.17" %}} The device ID supplied by the application service does
not belong to the user ID during [identity assertion](/application-service-api/#identity-assertion). not belong to the user ID during [identity assertion](/application-service-api/#identity-assertion).
`M_RESOURCE_LIMIT_EXCEEDED` `M_RESOURCE_LIMIT_EXCEEDED`
The request cannot be completed because the homeserver has reached a : The request cannot be completed because the homeserver has reached a
resource limit imposed on it. For example, a homeserver held in a shared resource limit imposed on it. For example, a homeserver held in a shared
hosting environment may reach a resource limit if it starts using too hosting environment may reach a resource limit if it starts using too
much memory or disk space. The error MUST have an `admin_contact` field much memory or disk space. The error MUST have an `admin_contact` field
@ -179,7 +179,7 @@ Example response:
``` ```
`M_UNKNOWN` `M_UNKNOWN`
An unknown error has occurred. : An unknown error has occurred.
#### Other error codes #### Other error codes
@ -188,90 +188,90 @@ The following error codes are specific to certain endpoints.
<!-- TODO: move them to the endpoints that return them --> <!-- TODO: move them to the endpoints that return them -->
`M_UNAUTHORIZED` `M_UNAUTHORIZED`
The request was not correctly authorized. Usually due to login failures. : The request was not correctly authorized. Usually due to login failures.
`M_USER_DEACTIVATED` `M_USER_DEACTIVATED`
The user ID associated with the request has been deactivated. Typically : The user ID associated with the request has been deactivated. Typically
for endpoints that prove authentication, such as [`/login`](#get_matrixclientv3login). for endpoints that prove authentication, such as [`/login`](#get_matrixclientv3login).
`M_USER_IN_USE` `M_USER_IN_USE`
Encountered when trying to register a user ID which has been taken. : Encountered when trying to register a user ID which has been taken.
`M_INVALID_USERNAME` `M_INVALID_USERNAME`
Encountered when trying to register a user ID which is not valid. : Encountered when trying to register a user ID which is not valid.
`M_ROOM_IN_USE` `M_ROOM_IN_USE`
Sent when the room alias given to the `createRoom` API is already in : Sent when the room alias given to the `createRoom` API is already in
use. use.
`M_INVALID_ROOM_STATE` `M_INVALID_ROOM_STATE`
Sent when the initial state given to the `createRoom` API is invalid. : Sent when the initial state given to the `createRoom` API is invalid.
`M_THREEPID_IN_USE` `M_THREEPID_IN_USE`
Sent when a threepid given to an API cannot be used because the same : Sent when a threepid given to an API cannot be used because the same
threepid is already in use. threepid is already in use.
`M_THREEPID_NOT_FOUND` `M_THREEPID_NOT_FOUND`
Sent when a threepid given to an API cannot be used because no record : Sent when a threepid given to an API cannot be used because no record
matching the threepid was found. matching the threepid was found.
`M_THREEPID_AUTH_FAILED` `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` `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 if the server only permits, for example, email addresses from a
particular domain. particular domain.
`M_SERVER_NOT_TRUSTED` `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. that this server does not trust.
`M_UNSUPPORTED_ROOM_VERSION` `M_UNSUPPORTED_ROOM_VERSION`
The client's request to create a room used a room version that the : The client's request to create a room used a room version that the
server does not support. server does not support.
`M_INCOMPATIBLE_ROOM_VERSION` `M_INCOMPATIBLE_ROOM_VERSION`
The client attempted to join a room that has a version the server does : The client attempted to join a room that has a version the server does
not support. Inspect the `room_version` property of the error response not support. Inspect the `room_version` property of the error response
for the room's version. for the room's version.
`M_BAD_STATE` `M_BAD_STATE`
The state change requested cannot be performed, such as attempting to : The state change requested cannot be performed, such as attempting to
unban a user who is not banned. unban a user who is not banned.
`M_GUEST_ACCESS_FORBIDDEN` `M_GUEST_ACCESS_FORBIDDEN`
The room or resource does not permit guests to access it. : The room or resource does not permit guests to access it.
`M_CAPTCHA_NEEDED` `M_CAPTCHA_NEEDED`
A Captcha is required to complete the request. : A Captcha is required to complete the request.
`M_CAPTCHA_INVALID` `M_CAPTCHA_INVALID`
The Captcha provided did not match what was expected. : The Captcha provided did not match what was expected.
`M_MISSING_PARAM` `M_MISSING_PARAM`
A required parameter was missing from the request. : A required parameter was missing from the request.
`M_INVALID_PARAM` `M_INVALID_PARAM`
A parameter that was specified has the wrong value. For example, the : A parameter that was specified has the wrong value. For example, the
server expected an integer and instead received a string. server expected an integer and instead received a string.
`M_TOO_LARGE` `M_TOO_LARGE`
The request or entity was too large. : The request or entity was too large.
`M_EXCLUSIVE` `M_EXCLUSIVE`
The resource being requested is reserved by an application service, or : The resource being requested is reserved by an application service, or
the application service making the request has not created the resource. the application service making the request has not created the resource.
`M_CANNOT_LEAVE_SERVER_NOTICE_ROOM` `M_CANNOT_LEAVE_SERVER_NOTICE_ROOM`
The user is unable to reject an invite to join the server notices room. : The user is unable to reject an invite to join the server notices room.
See the [Server Notices](#server-notices) module for more information. See the [Server Notices](#server-notices) module for more information.
`M_THREEPID_MEDIUM_NOT_SUPPORTED` `M_THREEPID_MEDIUM_NOT_SUPPORTED`
The homeserver does not support adding a third party identifier of the given medium. : The homeserver does not support adding a third party identifier of the given medium.
`M_THREEPID_IN_USE` `M_THREEPID_IN_USE`
The third party identifier specified by the client is not acceptable because it is : The third party identifier specified by the client is not acceptable because it is
already in use in some way. already in use in some way.
#### Rate limiting #### Rate limiting
@ -3351,7 +3351,7 @@ PUT /rooms/!roomid:domain/state/m.room.bgd.color
### Redactions ### Redactions
Since events are extensible it is possible for malicious users and/or Since events are extensible it is possible for malicious users and/or
servers to add keys that are, for example offensive or illegal. Since servers to add keys that are, for example, offensive or illegal. Since
some events cannot be simply deleted, e.g. membership events, we instead some events cannot be simply deleted, e.g. membership events, we instead
'redact' events. This involves removing all keys from an event that are 'redact' events. This involves removing all keys from an event that are
not required by the protocol. This stripped down event is thereafter not required by the protocol. This stripped down event is thereafter
@ -3449,7 +3449,7 @@ This specification describes the following relationship types:
* [Event replacements](#event-replacements). * [Event replacements](#event-replacements).
* [Event annotations](#event-annotations-and-reactions). * [Event annotations](#event-annotations-and-reactions).
* [Threads](#threading). * [Threads](#threading).
* [References](#reference-relations) * [References](#reference-relations).
#### Aggregations of child events #### Aggregations of child events

190
content/client-server-api/modules/end_to_end_encryption.md
View file

@ -5,6 +5,91 @@ Matrix optionally supports end-to-end encryption, allowing rooms to be
created whose conversation contents are not decryptable or interceptable created whose conversation contents are not decryptable or interceptable
on any of the participating homeservers. on any of the participating homeservers.
#### Recommended client behaviour
{{% added-in v="1.18" %}}
While clients are able to choose what encryption features they implement based
on their threat model, this section recommends behaviours that will improve the
overall user experience and security of encrypted conversations.
While a user may be unable to [verify](#device-verification) every other user
that they communicate with, or may be unaware of the need to verify other users,
[cross-signing](#cross-signing) gives some measure of protection and so SHOULD
be used where possible. In particular, clients SHOULD implement the following
recommendations.
* Clients SHOULD create new [cross-signing keys](#cross-signing) for users who
do not yet have cross-signing keys.
* Clients SHOULD encourage users to set up their [Secret Storage](#storage) to
avoid needing to reset their cryptographic identity in case the user does not
have an existing device that can [share the secrets](#sharing) with the new
device. The user's Secret Storage SHOULD contain the user's cross-signing
private keys and the [key backup](#server-side-key-backups) decryption key
(if the user is using key backup). The user's Secret Storage SHOULD have a
[default key](#key-storage) (a key referred to by
`m.secret_storage.default_key`) that encrypts the private cross-signing keys
and key backup decryption key (if available).
* Clients SHOULD encourage users to [cross-sign](#cross-signing) their devices.
This includes both when logging in a new device, and for existing devices.
Clients MAY even go so far as to require cross-signing of devices by
preventing the user from using the client until the device is cross-signed.
If the user cannot cross-sign their device (for example, if they have
forgotten their Secret Storage key), the client can allow users to reset their
[Secret Storage](#storage), cross-signing keys, and [key backup](#server-side-key-backups).
* When Alice [verifies](#device-verification) Bob, the verification SHOULD
verify their [cross-signing keys](#cross-signing). Any flow between different
users that does not verify the users' cross-signing keys (it verifies only the
device keys) is deprecated.
* Clients SHOULD flag when [cross-signing keys](#cross-signing) change. If
Alice's cross-signing keys change, Alice's own devices MUST alert her to this
fact, and prompt her to re-cross-sign those devices. If Bob is in an
encrypted room with Alice, Bob's devices SHOULD inform him of Alice's key
change and SHOULD prevent him from sending an encrypted message to Alice
without acknowledging the change. Bob's clients may behave differently
depending on whether Bob had previously [verified](#device-verification)
Alice or not. For example, if Bob had previously verified Alice, and Alice's
keys change, Bob's client may require Bob to re-verify, or may display a more
aggressive warning.
* Clients SHOULD NOT send encrypted [to-device](#send-to-device-messaging)
messages, such as [room keys](#sharing-keys-between-devices) or [secrets](#secrets)
(via [Secret Sharing](#sharing)), to [non-cross-signed](#cross-signing)
devices by default. Non-cross-signed devices don't provide any assurance that
the device belongs to the user, and server admins can trivially create new
devices for users. When sending room keys, clients can use a
[`m.room_key.withheld`](#mroom_keywithheld) message with a code of
`m.unverified` to indicate to the non-cross-signed device why it is not
receiving the room key.
Note that clients cannot selectively send room events only to cross-signed
devices. The only way to exclude non-cross-signed devices from encrypted
conversations is to not send the room keys so those devices won't be able to
decrypt the messages.
* Similarly, messages sent from [non-cross-signed](#cross-signing) devices
cannot be trusted and SHOULD NOT be displayed to the user. Clients have no
assurance that encrypted messages sent from non-cross-signed devices were sent
by the user, rather than an impersonator.
* Matrix clients MUST NOT consider non-cryptographic devices (devices which do
not have [device identity keys](#device-keys) uploaded to the homeserver) to
be equivalent to [non-cross-signed](#cross-signing) cryptographic devices for
purposes of enforcing E2EE policy. For example, clients SHOULD NOT warn nor
refuse to send messages due to the presence of non-cryptographic devices. For
all intents and purposes, non-cryptographic devices are a completely separate
concept and do not exist from the perspective of the cryptography layer since
they do not have identity keys, so it is impossible to send them decryption
keys.
* Clients MAY make provisions for encrypted bridges. Some bridges are structured
in a way such that only one user controlled by the bridge (often called the
bridge bot) participates in encryption, and encrypted messages from other
bridge users are encrypted by the bridge bot. Thus encrypted messages sent by
one user could be encrypted by a [Megolm](#mmegolmv1aes-sha2) session sent by
a different user. Clients MAY accept such messages, provided the session
creator's device is [cross-signed](#cross-signing). However, the client MUST
annotate the message with a warning, unless the client has a way to check that
the bridge bot is permitted to encrypt messages on behalf of the user. Future
MSCs such as [MSC4350](https://github.com/matrix-org/matrix-spec-proposals/pull/4350)
may provide a secure way to allow such impersonation.
#### Key Distribution #### Key Distribution
Encryption and Authentication in Matrix is based around public-key Encryption and Authentication in Matrix is based around public-key
@ -93,7 +178,7 @@ Example:
``` ```
`ed25519` and `curve25519` keys are used for [device keys](#device-keys). `ed25519` and `curve25519` keys are used for [device keys](#device-keys).
Additionally, `ed25519` keys are used for [cross-signing keys](#cross-signing). Additionally, `ed25519` keys are used for [cross-signing](#cross-signing).
`signed_curve25519` keys are used for [one-time and fallback keys](#one-time-and-fallback-keys). `signed_curve25519` keys are used for [one-time and fallback keys](#one-time-and-fallback-keys).
@ -674,8 +759,11 @@ The process between Alice and Bob verifying each other would be:
their devices if they match or not. their devices if they match or not.
15. Assuming they match, Alice and Bob's devices each calculate Message 15. Assuming they match, Alice and Bob's devices each calculate Message
Authentication Codes (MACs) for: Authentication Codes (MACs) for:
* Each of the keys that they wish the other user to verify (usually their * {{% changed-in v="1.18" %}} Each of the keys that they wish the other user
device ed25519 key and their master cross-signing key). to verify (usually their device ed25519 key and their master signing key,
see below). The master signing key SHOULD be included when two different
users are verifying each other. Verifying individual devices of other
users is deprecated.
* The complete list of key IDs that they wish the other user to verify. * The complete list of key IDs that they wish the other user to verify.
The MAC calculation is defined [below](#mac-calculation). The MAC calculation is defined [below](#mac-calculation).
@ -931,40 +1019,42 @@ and can be translated online:
Rather than requiring Alice to verify each of Bob's devices with each of Rather than requiring Alice to verify each of Bob's devices with each of
her own devices and vice versa, the cross-signing feature allows users her own devices and vice versa, the cross-signing feature allows users
to sign their device keys such that Alice and Bob only need to verify to sign their device keys such that Alice and Bob only need to verify
once. With cross-signing, each user has a set of cross-signing keys that once. With cross-signing, each user has a set of cross-signing key pairs that
are used to sign their own device keys and other users' keys, and can be are used to sign their own device keys and other users' keys, and can be
used to trust device keys that were not verified directly. used to trust device keys that were not verified directly.
Each user has three ed25519 key pairs for cross-signing: Each user has three ed25519 key pairs used for cross-signing (cross-signing keys):
- a master key (MSK) that serves as the user's identity in - a master signing key (MSK, for historical reasons sometimes known as
cross-signing and signs their other cross-signing keys; `master_key`) that serves as the user's identity in cross-signing and signs
their user-signing and self-signing keys;
- a user-signing key (USK) -- only visible to the user that it belongs - a user-signing key (USK) -- only visible to the user that it belongs
to --that signs other users' master keys; and to -- that signs other users' master signing keys; and
- a self-signing key (SSK) that signs the user's own device keys. - a self-signing key (SSK) that signs the user's own device keys.
The master key may also be used to sign other items such as the backup The master signing key may also be used to sign other items such as the backup
key. The master key may also be signed by the user's own device keys to key. The master signing key may also be signed by the user's own device keys to
aid in migrating from device verifications: if Alice's device had aid in migrating from device verifications: if Alice's device had
previously verified Bob's device and Bob's device has signed his master previously verified Bob's device and Bob's device has signed his master
key, then Alice's device can trust Bob's master key, and she can sign it key, then Alice's device can trust Bob's master signing key, and she can sign it
with her user-signing key. with her user-signing key.
Users upload their cross-signing keys to the server using [POST Users upload the public parts of their master signing, user-signing and
self-signing keys to the server using [POST
/\_matrix/client/v3/keys/device\_signing/upload](/client-server-api/#post_matrixclientv3keysdevice_signingupload). When Alice uploads /\_matrix/client/v3/keys/device\_signing/upload](/client-server-api/#post_matrixclientv3keysdevice_signingupload). When Alice uploads
new cross-signing keys, her user ID will appear in the `changed` new keys, her user ID will appear in the `changed`
property of the `device_lists` field of the `/sync` of response of all property of the `device_lists` field of the `/sync` of response of all
users who share an encrypted room with her. When Bob sees Alice's user users who share an encrypted room with her. When Bob sees Alice's user
ID in his `/sync`, he will call [POST /\_matrix/client/v3/keys/query](/client-server-api/#post_matrixclientv3keysquery) ID in his `/sync`, he will call [POST /\_matrix/client/v3/keys/query](/client-server-api/#post_matrixclientv3keysquery)
to retrieve Alice's device and cross-signing keys. to retrieve Alice's device keys, as well as their cross-signing keys.
If Alice has a device and wishes to send an encrypted message to Bob, If Alice has a device and wishes to send an encrypted message to Bob,
she can trust Bob's device if: she can trust Bob's device if:
- Alice's device is using a master key that has signed her - Alice's device is using a master signing key that has signed her
user-signing key, user-signing key,
- Alice's user-signing key has signed Bob's master key, - Alice's user-signing key has signed Bob's master signing key,
- Bob's master key has signed Bob's self-signing key, and - Bob's master signing key has signed Bob's self-signing key, and
- Bob's self-signing key has signed Bob's device key. - Bob's self-signing key has signed Bob's device key.
The following diagram illustrates how keys are signed: The following diagram illustrates how keys are signed:
@ -1024,27 +1114,28 @@ signatures that she cannot see:
``` ```
[Verification methods](#device-verification) can be used to verify a [Verification methods](#device-verification) can be used to verify a
user's master key by using the master public key, encoded using unpadded user's master signing key by treating its public key (master signing public
base64, as the device ID, and treating it as a normal device. For key), encoded using unpadded base64, as the device ID, and treating it as a
example, if Alice and Bob verify each other using SAS, Alice's normal device. For example, if Alice and Bob verify each other using SAS,
Alice's
`m.key.verification.mac` message to Bob may include `m.key.verification.mac` message to Bob may include
`"ed25519:alices+master+public+key": "alices+master+public+key"` in the `"ed25519:alices+master+public+key": "alices+master+public+key"` in the
`mac` property. Servers therefore must ensure that device IDs will not `mac` property. Servers therefore must ensure that device IDs will not
collide with cross-signing public keys. collide with cross-signing public keys.
The cross-signing private keys can be stored on the server or shared with other Using the [Secrets](#secrets) module the private parts of the cross-signing keys can
devices using the [Secrets](#secrets) module. When doing so, the master, be stored on the server or shared with other devices. When doing so, the
user-signing, and self-signing keys are identified using the names master signing, user-signing, and self-signing keys are identified using the
`m.cross_signing.master`, `m.cross_signing.user_signing`, and names `m.cross_signing.master`, `m.cross_signing.user_signing`, and
`m.cross_signing.self_signing`, respectively, and the keys are base64-encoded `m.cross_signing.self_signing`, respectively, and the keys are base64-encoded
before being encrypted. before being encrypted.
###### Key and signature security ###### Key and signature security
A user's master key could allow an attacker to impersonate that user to A user's master signing key could allow an attacker to impersonate that user to
other users, or other users to that user. Thus clients must ensure that other users, or other users to that user. Thus clients must ensure that
the private part of the master key is treated securely. If clients do the private part of the master signing key is treated securely. If clients do
not have a secure means of storing the master key (such as a secret not have a secure means of storing the master signing key (such as a secret
storage system provided by the operating system), then clients must not storage system provided by the operating system), then clients must not
store the private part. store the private part.
@ -1057,9 +1148,9 @@ Since device key IDs (`ed25519:DEVICE_ID`) and cross-signing key IDs
use the correct keys when verifying. use the correct keys when verifying.
While servers MUST not allow devices to have the same IDs as cross-signing While servers MUST not allow devices to have the same IDs as cross-signing
keys, a malicious server could construct such a situation, so clients must not keys, a malicious server could construct such a situation, so clients
rely on the server being well-behaved and should take the following precautions must not rely on the server being well-behaved and should take the following
against this. precautions against this:
1. Clients MUST refer to keys by their public keys during the verification 1. Clients MUST refer to keys by their public keys during the verification
process, rather than only by the key ID. process, rather than only by the key ID.
@ -1067,31 +1158,32 @@ against this.
verification process, and ensure that they do not change in the course of verification process, and ensure that they do not change in the course of
verification. verification.
3. Clients SHOULD also display a warning and MUST refuse to verify a user when 3. Clients SHOULD also display a warning and MUST refuse to verify a user when
they detect that the user has a device with the same ID as a cross-signing key. they detect that the user has a device with the same ID as a cross-signing
key.
A user's user-signing and self-signing keys are intended to be easily A user's user-signing and self-signing keys are intended to be easily
replaceable if they are compromised by re-issuing a new key signed by replaceable if they are compromised by re-issuing a new key signed by
the user's master key and possibly by re-verifying devices or users. the user's master signing key and possibly by re-verifying devices or users.
However, doing so relies on the user being able to notice when their However, doing so relies on the user being able to notice when their
keys have been compromised, and it involves extra work for the user, and keys have been compromised, and it involves extra work for the user, and
so although clients do not have to treat the private parts as so although clients do not have to treat the private parts as
sensitively as the master key, clients should still make efforts to sensitively as the master signing key, clients should still make efforts to
store the private part securely, or not store it at all. Clients will store the private part securely, or not store it at all. Clients will
need to balance the security of the keys with the usability of signing need to balance the security of the keys with the usability of signing
users and devices when performing key verification. users and devices when performing key verification.
To avoid leaking of social graphs, servers will only allow users to see: To avoid leaking of social graphs, servers will only allow users to see:
- signatures made by the user's own master, self-signing or - signatures made by the user's own master signing, self-signing or
user-signing keys, user-signing keys,
- signatures made by the user's own devices about their own master - signatures made by the user's own devices about their own master
key, key,
- signatures made by other users' self-signing keys about their - signatures made by other users' self-signing keys about their
respective devices, respective devices,
- signatures made by other users' master keys about their respective - signatures made by other users' master signing keys about their respective
self-signing key, or self-signing key, or
- signatures made by other users' devices about their respective - signatures made by other users' devices about their respective
master keys. master signing keys.
Users will not be able to see signatures made by other users' Users will not be able to see signatures made by other users'
user-signing keys. user-signing keys.
@ -1193,24 +1285,24 @@ The binary segment MUST be of the following form:
- one byte indicating the QR code verification mode. Should be one of the - one byte indicating the QR code verification mode. Should be one of the
following values: following values:
- `0x00` verifying another user with cross-signing - `0x00` verifying another user with cross-signing
- `0x01` self-verifying in which the current device does trust the master key - `0x01` self-verifying in which the current device does trust the master signing key
- `0x02` self-verifying in which the current device does not yet trust the - `0x02` self-verifying in which the current device does not yet trust the
master key master signing key
- the event ID or `transaction_id` of the associated verification - the event ID or `transaction_id` of the associated verification
request event, encoded as: request event, encoded as:
- two bytes in network byte order (big-endian) indicating the length in - two bytes in network byte order (big-endian) indicating the length in
bytes of the ID as a UTF-8 string bytes of the ID as a UTF-8 string
- the ID encoded as a UTF-8 string - the ID encoded as a UTF-8 string
- the first key, as 32 bytes. The key to use depends on the mode field: - the first key, as 32 bytes. The key to use depends on the mode field:
- if `0x00` or `0x01`, then the current user's own master cross-signing public key - if `0x00` or `0x01`, then the current user's own master signing public key
- if `0x02`, then the current device's Ed25519 signing key - if `0x02`, then the current device's Ed25519 signing key
- the second key, as 32 bytes. The key to use depends on the mode field: - the second key, as 32 bytes. The key to use depends on the mode field:
- if `0x00`, then what the device thinks the other user's master - if `0x00`, then what the device thinks the other user's master
cross-signing public key is public key is
- if `0x01`, then what the device thinks the other device's Ed25519 signing - if `0x01`, then what the device thinks the other device's Ed25519 signing
public key is public key is
- if `0x02`, then what the device thinks the user's master cross-signing public - if `0x02`, then what the device thinks the user's master signing public key
key is is
- a random shared secret, as a sequence of bytes. It is suggested to use a secret - a random shared secret, as a sequence of bytes. It is suggested to use a secret
that is about 8 bytes long. Note: as we do not share the length of the that is about 8 bytes long. Note: as we do not share the length of the
secret, and it is not a fixed size, clients will just use the remainder of secret, and it is not a fixed size, clients will just use the remainder of
@ -1221,14 +1313,14 @@ For example, if Alice displays a QR code encoding the following binary data:
```nohighlight ```nohighlight
"MATRIX" |ver|mode| len | event ID "MATRIX" |ver|mode| len | event ID
4D 41 54 52 49 58 02 00 00 2D 21 41 42 43 44 ... 4D 41 54 52 49 58 02 00 00 2D 21 41 42 43 44 ...
| user's cross-signing key | other user's cross-signing key | shared secret | the first key | the second key | shared secret
00 01 02 03 04 05 06 07 ... 10 11 12 13 14 15 16 17 ... 20 21 22 23 24 25 26 27 00 01 02 03 04 05 06 07 ... 10 11 12 13 14 15 16 17 ... 20 21 22 23 24 25 26 27
``` ```
this indicates that Alice is verifying another user (say Bob), in response to Mode `0x00` indicates that Alice is verifying another user (say Bob), in
the request from event "$ABCD...", her cross-signing key is response to the request from event "$ABCD...", her master signing key is
`0001020304050607...` (which is "AAECAwQFBg..." in base64), she thinks that `0001020304050607...` (which is "AAECAwQFBg..." in base64), she thinks that
Bob's cross-signing key is `1011121314151617...` (which is "EBESExQVFh..." in Bob's master signing key is `1011121314151617...` (which is "EBESExQVFh..." in
base64), and the shared secret is `2021222324252627` (which is "ICEiIyQlJic" in base64), and the shared secret is `2021222324252627` (which is "ICEiIyQlJic" in
base64). base64).
@ -1300,8 +1392,8 @@ one of its variants.
Clients must only store keys in backups after they have ensured that the Clients must only store keys in backups after they have ensured that the
`auth_data` is trusted. This can be done either by: `auth_data` is trusted. This can be done either by:
- checking that it is signed by the user's [master cross-signing - checking that it is signed by the user's [master signing key](#cross-signing)
key](#cross-signing) or by a verified device belonging to the same user, or or by a verified device belonging to the same user, or
- deriving the public key from a private key that it obtained from a trusted - deriving the public key from a private key that it obtained from a trusted
source. Trusted sources for the private key include the user entering the source. Trusted sources for the private key include the user entering the
key, retrieving the key stored in [secret storage](#secret-storage), or key, retrieving the key stored in [secret storage](#secret-storage), or

2
content/client-server-api/modules/threading.md
View file

@ -107,7 +107,7 @@ flag to `true`.
``` ```
{{% boxes/note %}} {{% boxes/note %}}
Clients which are acutely aware of threads (they do not render threads, but are otherwise Clients which are aware of threads (they do not render threads, but are otherwise
aware of the feature existing in the spec) can treat rich replies to an event with a `rel_type` aware of the feature existing in the spec) can treat rich replies to an event with a `rel_type`
of `m.thread` as a threaded reply, for conversation continuity on the threaded client's side. of `m.thread` as a threaded reply, for conversation continuity on the threaded client's side.

28
content/identity-service-api.md
View file

@ -71,53 +71,53 @@ the keys `error` and `errcode` MUST always be present.
Some standard error codes are below: Some standard error codes are below:
`M_NOT_FOUND` `M_NOT_FOUND`
The resource requested could not be located. : The resource requested could not be located.
`M_MISSING_PARAMS` `M_MISSING_PARAMS`
The request was missing one or more parameters. : The request was missing one or more parameters.
`M_INVALID_PARAM` `M_INVALID_PARAM`
The request contained one or more invalid parameters. : The request contained one or more invalid parameters.
`M_SESSION_NOT_VALIDATED` `M_SESSION_NOT_VALIDATED`
The session has not been validated. : The session has not been validated.
`M_NO_VALID_SESSION` `M_NO_VALID_SESSION`
A session could not be located for the given parameters. : A session could not be located for the given parameters.
`M_SESSION_EXPIRED` `M_SESSION_EXPIRED`
The session has expired and must be renewed. : The session has expired and must be renewed.
`M_INVALID_EMAIL` `M_INVALID_EMAIL`
The email address provided was not valid. : The email address provided was not valid.
`M_EMAIL_SEND_ERROR` `M_EMAIL_SEND_ERROR`
There was an error sending an email. Typically seen when attempting to : There was an error sending an email. Typically seen when attempting to
verify ownership of a given email address. verify ownership of a given email address.
`M_INVALID_ADDRESS` `M_INVALID_ADDRESS`
The provided third-party address was not valid. : The provided third-party address was not valid.
`M_SEND_ERROR` `M_SEND_ERROR`
There was an error sending a notification. Typically seen when : 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` `M_UNRECOGNIZED`
The request contained an unrecognised value, such as an unknown token or : The request contained an unrecognised value, such as an unknown token or
medium. medium.
This is also used as the response if a server did not understand the request. : This is also used as the response if a server did not understand the request.
This is expected to be returned with a 404 HTTP status code if the endpoint is This is expected to be returned with a 404 HTTP status code if the endpoint is
not implemented or a 405 HTTP status code if the endpoint is implemented, but not implemented or a 405 HTTP status code if the endpoint is implemented, but
the incorrect HTTP method is used. the incorrect HTTP method is used.
`M_THREEPID_IN_USE` `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 this error will have an additional `mxid` property to indicate who owns
the third-party identifier. the third-party identifier.
`M_UNKNOWN` `M_UNKNOWN`
An unknown error has occurred. : An unknown error has occurred.
## Privacy ## Privacy

41
content/rooms/fragments/v1-floaty-power-levels.md Normal file
View file

@ -0,0 +1,41 @@
##### `m.room.power_levels` events accept values as floats
When the value is a float
* First, exponential notation is applied: `5.114698E4` becomes `51146.98`
* Second, the value is truncated at the decimal point: `51146.98` becomes `51146`.
Values outside the range represented by IEE754 binary64 (a "double") cause the
powerlevel event to be rejected, as do `Infinity`, `-Infinity` and `NaN`.
For example, this is a valid `m.room.power_levels` event in this room version:
```json
{
"content": {
"ban": 50,
"events": {
"m.room.power_levels": 100
},
"events_default": 0,
"state_default": 50,
"users": {
"@example:example.org": 100,
"@alice:localhost": 50,
"@bob:localhost": 50.57
},
"users_default": 0
},
"origin_server_ts": 1432735824653,
"room_id": "!jEsUZKDJdhlrceRyVU:example.org",
"sender": "@example:example.org",
"state_key": "",
"type": "m.room.power_levels"
}
```
In this example, both `@bob:localhost` and `@alice:localhost` have the same effective
power level of `50`, even though the values are technically different.
Note that, since this room version does not enforce that events comply with the requirements
of [Canonical JSON](/appendices#canonical-json), power levels can be formatted as floats.

2
content/rooms/v1.md
View file

@ -59,6 +59,8 @@ Events in version 1 rooms have the following structure:
{{% rver-fragment name="v1-stringy-power-levels" %}} {{% rver-fragment name="v1-stringy-power-levels" %}}
{{% rver-fragment name="v1-floaty-power-levels" %}}
### Authorization rules ### Authorization rules
{{% rver-fragment name="v1-auth-rules" %}} {{% rver-fragment name="v1-auth-rules" %}}

2
content/rooms/v2.md
View file

@ -57,6 +57,8 @@ Events in rooms of this version have the following structure:
{{% rver-fragment name="v1-stringy-power-levels" %}} {{% rver-fragment name="v1-stringy-power-levels" %}}
{{% rver-fragment name="v1-floaty-power-levels" %}}
### Authorization rules ### Authorization rules
{{% rver-fragment name="v1-auth-rules" %}} {{% rver-fragment name="v1-auth-rules" %}}

2
content/rooms/v3.md
View file

@ -87,6 +87,8 @@ The complete structure of a event in a v3 room is shown below.
{{% rver-fragment name="v1-stringy-power-levels" %}} {{% rver-fragment name="v1-stringy-power-levels" %}}
{{% rver-fragment name="v1-floaty-power-levels" %}}
### Authorization rules ### Authorization rules
{{% boxes/note %}} {{% boxes/note %}}

2
content/rooms/v4.md
View file

@ -76,6 +76,8 @@ the changes in this room version.
{{% rver-fragment name="v1-stringy-power-levels" %}} {{% rver-fragment name="v1-stringy-power-levels" %}}
{{% rver-fragment name="v1-floaty-power-levels" %}}
### Authorization rules ### Authorization rules
{{% rver-fragment name="v3-auth-rules" %}} {{% rver-fragment name="v3-auth-rules" %}}

2
content/rooms/v5.md
View file

@ -58,6 +58,8 @@ completeness.
{{% rver-fragment name="v1-stringy-power-levels" %}} {{% rver-fragment name="v1-stringy-power-levels" %}}
{{% rver-fragment name="v1-floaty-power-levels" %}}
### Authorization rules ### Authorization rules
{{% rver-fragment name="v3-auth-rules" %}} {{% rver-fragment name="v3-auth-rules" %}}

3
content/rooms/v6.md
View file

@ -42,7 +42,8 @@ in [room version 5](/rooms/v5).
### Event format ### Event format
{{% added-in v=6 %}} Through enforcement of [Canonical JSON](#canonical-json), {{% added-in v=6 %}} Through enforcement of [Canonical JSON](#canonical-json),
the `depth` limit has been reduced in this room version. the `depth` limit has been reduced in this room version, and numeric values may
no longer be formatted as floats.
{{% rver-fragment name="v6-event-format" %}} {{% rver-fragment name="v6-event-format" %}}

6
content/server-server-api.md
View file

@ -868,8 +868,10 @@ selecting a resident from the candidate list, and using the
enough information for the joining server to fill in the event. enough information for the joining server to fill in the event.
The joining server is expected to add or replace the `origin`, The joining server is expected to add or replace the `origin`,
`origin_server_ts`, and `event_id` on the templated event received by `origin_server_ts`, and `event_id` on the templated event received by the
the resident server. This event is then signed by the joining server. resident server. The joining server MUST also verify that the `type`, `room_id`,
`sender`, `state_key` and `content.membership` fields have the expected values.
This event is then signed by the joining server.
To complete the join handshake, the joining server submits this new event To complete the join handshake, the joining server submits this new event
to the resident server it used for `GET /make_join`, using the `PUT /send_join` to the resident server it used for `GET /make_join`, using the `PUT /send_join`

18
data/api/client-server/cross_signing.yaml
View file

@ -32,9 +32,9 @@ paths:
except when used by an application service. except when used by an application service.
User-Interactive Authentication MUST be performed for regular clients, except in these cases: User-Interactive Authentication MUST be performed for regular clients, except in these cases:
- there is no existing cross-signing master key uploaded to the homeserver, OR - there is no existing master signing key uploaded to the homeserver, OR
- there is an existing cross-signing master key and it exactly matches the - there is an existing master signing key and it exactly matches the
cross-signing master key provided in the request body. If there are any additional master signing key provided in the request body. If there are any additional
keys provided in the request (self-signing key, user-signing key) they MUST also keys provided in the request (self-signing key, user-signing key) they MUST also
match the existing keys stored on the server. In other words, the request contains match the existing keys stored on the server. In other words, the request contains
no new keys. no new keys.
@ -61,22 +61,22 @@ paths:
type: object type: object
properties: properties:
master_key: master_key:
description: Optional. The user\'s master key. description: Optional. The user\'s master signing key.
allOf: allOf:
- $ref: definitions/cross_signing_key.yaml - $ref: definitions/cross_signing_key.yaml
self_signing_key: self_signing_key:
description: |- description: |-
Optional. The user\'s self-signing key. Must be signed by Optional. The user\'s self-signing key. Must be signed by
the accompanying master key, or by the user\'s most recently the accompanying master signing key, or by the user\'s most recently
uploaded master key if no master key is included in the uploaded master signing key if no master signing key is included in the
request. request.
allOf: allOf:
- $ref: definitions/cross_signing_key.yaml - $ref: definitions/cross_signing_key.yaml
user_signing_key: user_signing_key:
description: |- description: |-
Optional. The user\'s user-signing key. Must be signed by Optional. The user\'s user-signing key. Must be signed by
the accompanying master key, or by the user\'s most recently the accompanying master signing key, or by the user\'s most recently
uploaded master key if no master key is included in the uploaded master signing key if no master signing key is included in the
request. request.
allOf: allOf:
- $ref: definitions/cross_signing_key.yaml - $ref: definitions/cross_signing_key.yaml
@ -147,7 +147,7 @@ paths:
* `M_INVALID_SIGNATURE`: For example, the self-signing or * `M_INVALID_SIGNATURE`: For example, the self-signing or
user-signing key had an incorrect signature. user-signing key had an incorrect signature.
* `M_MISSING_PARAM`: No master key is available. * `M_MISSING_PARAM`: No master signing key is available.
content: content:
application/json: application/json:
schema: schema:

6
data/api/client-server/definitions/cross_signing_key.yaml
View file

@ -13,7 +13,7 @@
# limitations under the License. # limitations under the License.
type: object type: object
title: CrossSigningKey title: CrossSigningKey
description: Cross signing key description: Key used for cross signing
properties: properties:
user_id: user_id:
type: string type: string
@ -44,8 +44,8 @@ properties:
title: Signatures title: Signatures
description: |- description: |-
Signatures of the key, calculated using the process described at [Signing JSON](/appendices/#signing-json). Signatures of the key, calculated using the process described at [Signing JSON](/appendices/#signing-json).
Optional for the master key. Other keys must be signed by the Optional for the master signing key. Other keys must be signed by the
user\'s master key. user\'s master signing key.
example: { example: {
"@alice:example.com": { "@alice:example.com": {
"ed25519:alice+base64+master+key": "signature+of+key" "ed25519:alice+base64+master+key": "signature+of+key"

6
data/api/client-server/definitions/event_filter.yaml
View file

@ -23,14 +23,14 @@ properties:
not_senders: not_senders:
description: A list of sender IDs to exclude. If this list is absent then no senders description: A list of sender IDs to exclude. If this list is absent then no senders
are excluded. A matching sender will be excluded even if it is listed in the are excluded. A matching sender will be excluded even if it is listed in the
`'senders'` filter. `senders` filter.
items: items:
type: string type: string
type: array type: array
not_types: not_types:
description: A list of event types to exclude. If this list is absent then no description: A list of event types to exclude. If this list is absent then no
event types are excluded. A matching type will be excluded even if it is listed event types are excluded. A matching type will be excluded even if it is listed
in the `'types'` filter. A '*' can be used as a wildcard to match any sequence in the `types` filter. A `*` can be used as a wildcard to match any sequence
of characters. of characters.
items: items:
type: string type: string
@ -43,7 +43,7 @@ properties:
type: array type: array
types: types:
description: A list of event types to include. If this list is absent then all description: A list of event types to include. If this list is absent then all
event types are included. A `'*'` can be used as a wildcard to match any sequence event types are included. A `*` can be used as a wildcard to match any sequence
of characters. of characters.
items: items:
type: string type: string

2
data/api/client-server/definitions/room_event_filter.yaml
View file

@ -39,7 +39,7 @@ allOf:
for more information. Defaults to `false`. for more information. Defaults to `false`.
not_rooms: not_rooms:
description: A list of room IDs to exclude. If this list is absent then no rooms description: A list of room IDs to exclude. If this list is absent then no rooms
are excluded. A matching room will be excluded even if it is listed in the `'rooms'` are excluded. A matching room will be excluded even if it is listed in the `rooms`
filter. filter.
items: items:
type: string type: string

12
data/api/client-server/definitions/sync_filter.yaml
View file

@ -17,15 +17,15 @@ properties:
event_fields: event_fields:
description: List of event fields to include. If this list is absent then all description: List of event fields to include. If this list is absent then all
fields are included. The entries are [dot-separated paths for each property](/appendices#dot-separated-property-paths) fields are included. The entries are [dot-separated paths for each property](/appendices#dot-separated-property-paths)
to include. So ['content.body'] will include the 'body' field of the 'content' object. to include. So `['content.body']` will include the `body` field of the `content` object.
A server may include more fields than were requested. A server may include more fields than were requested.
items: items:
type: string type: string
type: array type: array
event_format: event_format:
description: The format to use for events. 'client' will return the events in description: The format to use for events. `client` will return the events in
a format suitable for clients. 'federation' will return the raw event as received a format suitable for clients. `federation` will return the raw event as received
over federation. The default is 'client'. over federation. The default is `client`.
enum: enum:
- client - client
- federation - federation
@ -45,7 +45,7 @@ properties:
properties: properties:
not_rooms: not_rooms:
description: A list of room IDs to exclude. If this list is absent then no rooms description: A list of room IDs to exclude. If this list is absent then no rooms
are excluded. A matching room will be excluded even if it is listed in the `'rooms'` are excluded. A matching room will be excluded even if it is listed in the `rooms`
filter. This filter is applied before the filters in `ephemeral`, filter. This filter is applied before the filters in `ephemeral`,
`state`, `timeline` or `account_data` `state`, `timeline` or `account_data`
items: items:
@ -65,7 +65,7 @@ properties:
events that appear in the `ephemeral` property in the `/sync` events that appear in the `ephemeral` property in the `/sync`
response. response.
include_leave: include_leave:
description: Include rooms that the user has left in the sync, default false description: Include rooms that the user has left in the sync. Defaults to `false`.
type: boolean type: boolean
state: state:
type: object type: object

4
data/api/client-server/keys.yaml
View file

@ -219,8 +219,8 @@ paths:
x-addedInMatrixVersion: "1.1" x-addedInMatrixVersion: "1.1"
type: object type: object
description: |- description: |-
Information on the master cross-signing keys of the queried users. Information on the master signing keys of the queried users.
A map from user ID, to master key information. For each key, the A map from user ID, to master signing key information. For each key, the
information returned will be the same as uploaded via information returned will be the same as uploaded via
`/keys/device_signing/upload`, along with the signatures `/keys/device_signing/upload`, along with the signatures
uploaded via `/keys/signatures/upload` that the requesting user uploaded via `/keys/signatures/upload` that the requesting user

4
data/api/client-server/list_public_rooms.yaml
View file

@ -226,7 +226,7 @@ paths:
type: boolean type: boolean
description: |- description: |-
Whether or not to include all known networks/protocols from Whether or not to include all known networks/protocols from
application services on the homeserver. Defaults to false. application services on the homeserver. Defaults to `false`.
example: false example: false
third_party_instance_id: third_party_instance_id:
type: string type: string
@ -277,4 +277,4 @@ components:
accessTokenQuery: accessTokenQuery:
$ref: definitions/security.yaml#/accessTokenQuery $ref: definitions/security.yaml#/accessTokenQuery
accessTokenBearer: accessTokenBearer:
$ref: definitions/security.yaml#/accessTokenBearer $ref: definitions/security.yaml#/accessTokenBearer

17
data/api/client-server/login.yaml
View file

@ -70,6 +70,21 @@ paths:
} }
] ]
} }
"404":
description: |-
With `M_UNRECOGNIZED`: the homeserver does not support the legacy authentication API.
(See [Authentication API discovery](/client-server-api/#authentication-api-discovery).)
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value:
{
"errcode": "M_UNRECOGNIZED",
"error": "OAuth 2.0 authentication is in use on this homeserver.",
}
"429": "429":
description: This request was rate-limited. description: This request was rate-limited.
content: content:
@ -148,7 +163,7 @@ paths:
known client device, a new device will be created. The given known client device, a new device will be created. The given
device ID must not be the same as a device ID must not be the same as a
[cross-signing](/client-server-api/#cross-signing) key ID. [cross-signing](/client-server-api/#cross-signing) key ID.
The server will auto-generate a device_id The server will auto-generate a `device_id`
if this is not specified. if this is not specified.
initial_device_display_name: initial_device_display_name:
type: string type: string

15
data/api/client-server/oauth_server_metadata.yaml
View file

@ -195,6 +195,21 @@ paths:
"org.matrix.cross_signing_reset", "org.matrix.cross_signing_reset",
], ],
} }
"404":
description: |-
With `M_UNRECOGNIZED`: the homeserver does not support the OAuth 2.0 API.
(See [Authentication API discovery](/client-server-api/#authentication-api-discovery).)
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value:
{
"errcode": "M_UNRECOGNIZED",
"error": "Legacy authentication is in use on this homeserver.",
}
tags: tags:
- Session management - Session management
servers: servers:

2
data/api/client-server/password_management.yaml
View file

@ -57,7 +57,7 @@ paths:
type: boolean type: boolean
description: |- description: |-
Whether the user's other access tokens, and their associated devices, should be Whether the user's other access tokens, and their associated devices, should be
revoked if the request succeeds. Defaults to true. revoked if the request succeeds. Defaults to `true`.
When `false`, the server can still take advantage of the [soft logout method](/client-server-api/#soft-logout) When `false`, the server can still take advantage of the [soft logout method](/client-server-api/#soft-logout)
for the user's remaining devices. for the user's remaining devices.

6
data/api/client-server/registration.yaml
View file

@ -126,7 +126,7 @@ paths:
description: |- description: |-
ID of the client device. If this does not correspond to a ID of the client device. If this does not correspond to a
known client device, a new device will be created. The server known client device, a new device will be created. The server
will auto-generate a device_id if this is not specified. will auto-generate a `device_id` if this is not specified.
example: GHTYAJCE example: GHTYAJCE
initial_device_display_name: initial_device_display_name:
type: string type: string
@ -139,11 +139,11 @@ paths:
description: |- description: |-
If true, an `access_token` and `device_id` should not be If true, an `access_token` and `device_id` should not be
returned from this call, therefore preventing an automatic returned from this call, therefore preventing an automatic
login. Defaults to false. login. Defaults to `false`.
example: false example: false
refresh_token: refresh_token:
type: boolean type: boolean
description: If true, the client supports refresh tokens. description: If `true`, the client supports refresh tokens.
x-addedInMatrixVersion: "1.3" x-addedInMatrixVersion: "1.3"
required: true required: true
responses: responses:

28
data/api/client-server/report_content.yaml
View file

@ -25,6 +25,15 @@ paths:
the appropriate people. How such information is delivered is left up to the appropriate people. How such information is delivered is left up to
implementations. The caller is not required to be joined to the room to implementations. The caller is not required to be joined to the room to
report it. report it.
Clients could infer whether a reported room exists based on the 404 response.
Homeservers that wish to conceal this information MAY return 200 responses
regardless of the existence of the reported room.
Furthermore, it might be possible for clients to deduce whether a reported
room exists by timing the response. This is because only a report for an
existing room will require the homeserver to do further processing. To
combat this, homeservers MAY add a random delay when generating a response.
operationId: reportRoom operationId: reportRoom
parameters: parameters:
- in: path - in: path
@ -52,6 +61,11 @@ paths:
security: security:
- accessTokenQuery: [] - accessTokenQuery: []
- accessTokenBearer: [] - accessTokenBearer: []
x-changedInMatrixVersion:
1.18: |
Servers MAY prevent room ID enumeration by using the 200 response
regardless of the existence of the reported room and/or by adding
a random delay when generating responses.
responses: responses:
"200": "200":
description: The room has been reported successfully. description: The room has been reported successfully.
@ -91,6 +105,10 @@ paths:
the appropriate people. The caller must be joined to the room to report the appropriate people. The caller must be joined to the room to report
it. it.
Clients could infer whether a reported event or room exists based on the 404
response. Homeservers that wish to conceal this information MAY return 200
responses regardless of the existence of the reported event or room.
Furthermore, it might be possible for clients to deduce whether a reported Furthermore, it might be possible for clients to deduce whether a reported
event exists by timing the response. This is because only a report for an event exists by timing the response. This is because only a report for an
existing event will require the homeserver to do further processing. To existing event will require the homeserver to do further processing. To
@ -117,15 +135,9 @@ paths:
schema: schema:
type: object type: object
example: { example: {
"score": -100,
"reason": "this makes me sad" "reason": "this makes me sad"
} }
properties: properties:
score:
type: integer
description: |-
The score to rate this content as where -100 is most offensive
and 0 is inoffensive.
reason: reason:
type: string type: string
description: The reason the content is being reported. description: The reason the content is being reported.
@ -136,6 +148,10 @@ paths:
x-changedInMatrixVersion: x-changedInMatrixVersion:
1.8: | 1.8: |
This endpoint now requires the user to be joined to the room. This endpoint now requires the user to be joined to the room.
1.18: |
The `score` request parameter was removed. Additionally, servers
may prevent event/room ID enumeration by using the 200 response
regardless of the existence of the reported event/room.
responses: responses:
"200": "200":
description: The event has been reported successfully. description: The event has been reported successfully.

2
data/api/client-server/room_send.yaml
View file

@ -31,7 +31,7 @@ paths:
The body of the request should be the content object of the event; the The body of the request should be the content object of the event; the
fields in this object will vary depending on the type of event. See fields in this object will vary depending on the type of event. See
[Room Events](/client-server-api/#room-events) for the m. event specification. [Room Events](/client-server-api/#room-events) for the `m.` event specification.
Homeservers MUST allow clients to send `m.room.redaction` events with this Homeservers MUST allow clients to send `m.room.redaction` events with this
endpoint for all room versions. In rooms with a version older than 11 they endpoint for all room versions. In rooms with a version older than 11 they

45
data/api/server-server/invites-v1.yaml
View file

@ -36,6 +36,28 @@ paths:
Also note that if the remote homeserver is already in the room, it will receive the Also note that if the remote homeserver is already in the room, it will receive the
invite event twice; once through this endpoint, and again through a [federation invite event twice; once through this endpoint, and again through a [federation
transaction](/server-server-api/#transactions). transaction](/server-server-api/#transactions).
Servers MUST apply certain validation to ensure they don't accidentally sign non-invite
events from a malicious server. A specific error code is not mandated, but servers SHOULD
return `M_INVALID_PARAM` if:
* The invite event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
* The event type is not `m.room.member`.
* The `membership` field inside the event content is not `invite`.
* The event sender is not a user ID on the origin server.
* The `state_key` is not a user ID on the receiving server.
The `invite_room_state` has additional validation, which servers MAY apply to room versions
1 through 11 and SHOULD apply to all other room versions. As with the above errors, servers
SHOULD return `M_INVALID_PARAM` if:
* The `m.room.create` event is missing from `invite_room_state`.
* One or more entries in `invite_room_state` are not formatted according
to the room's version.
* One or more events fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
* One or more events does not reside in the same room as the invite.
Note: Some room versions may require calculating the room ID for an
event rather than relying on the presence of `room_id`.
operationId: sendInviteV1 operationId: sendInviteV1
security: security:
- signedRequest: [] - signedRequest: []
@ -83,8 +105,7 @@ paths:
MUST additionally be formatted according to the room version specification. MUST additionally be formatted according to the room version specification.
Servers might need to apply validation to the `invite_room_state` depending Servers might need to apply validation to the `invite_room_state` depending
on room version. See the `400 M_MISSING_PARAM` error definition for more on room version. See endpoint description for more information.
information.
Note that events have a different format depending on the room Note that events have a different format depending on the room
version - check the [room version specification](/rooms) for version - check the [room version specification](/rooms) for
@ -178,23 +199,7 @@ paths:
} }
"400": "400":
description: |- description: |-
The `M_MISSING_PARAM` error code is used to indicate one or more of The request is invalid in some way.
the following:
* The `m.room.create` event is missing from `invite_room_state`.
* One or more entries in `invite_room_state` are not formatted according
to the room's version.
* One or more events fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
* One or more events does not reside in the same room as the invite.
Note: Some room versions may require calculating the room ID for an
event rather than relying on the presence of `room_id`.
Servers MAY apply the validation above to room versions 1 through 11,
and SHOULD apply the validation above to all other room versions.
If `M_MISSING_PARAM` is returned and the request is associated with a
Client-Server API request, the Client-Server API request SHOULD fail
with a 5xx error rather than being passed through.
content: content:
application/json: application/json:
schema: schema:
@ -202,7 +207,7 @@ paths:
examples: examples:
response: response:
value: { value: {
"errcode": "M_MISSING_PARAM", "errcode": "M_INVALID_PARAM",
"error": "Create event not among invite state entries." "error": "Create event not among invite state entries."
} }
servers: servers:

43
data/api/server-server/invites-v2.yaml
View file

@ -40,6 +40,28 @@ paths:
Also note that if the remote homeserver is already in the room, it will receive the Also note that if the remote homeserver is already in the room, it will receive the
invite event twice; once through this endpoint, and again through a [federation invite event twice; once through this endpoint, and again through a [federation
transaction](/server-server-api/#transactions). transaction](/server-server-api/#transactions).
Servers MUST apply certain validation to ensure they don't accidentally sign non-invite
events from a malicious server. A specific error code is not mandated, but servers SHOULD
return `M_INVALID_PARAM` if:
* The invite event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
* The event type is not `m.room.member`.
* The `membership` field inside the event content is not `invite`.
* The event sender is not a user ID on the origin server.
* The `state_key` is not a user ID on the receiving server.
The `invite_room_state` has additional validation, which servers MAY apply to room versions
1 through 11 and SHOULD apply to all other room versions. As with the above errors, servers
SHOULD return `M_INVALID_PARAM` if:
* The `m.room.create` event is missing from `invite_room_state`.
* One or more entries in `invite_room_state` are not formatted according
to the room's version.
* One or more events fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
* One or more events does not reside in the same room as the invite.
Note: Some room versions may require calculating the room ID for an
event rather than relying on the presence of `room_id`.
operationId: sendInviteV2 operationId: sendInviteV2
security: security:
- signedRequest: [] - signedRequest: []
@ -84,8 +106,7 @@ paths:
MUST additionally be formatted according to the room version specification. MUST additionally be formatted according to the room version specification.
Servers might need to apply validation to the `invite_room_state` depending Servers might need to apply validation to the `invite_room_state` depending
on room version. See the `400 M_MISSING_PARAM` error definition for more on room version. See the endpoint description for more information.
information.
Note that events have a different format depending on the room Note that events have a different format depending on the room
version - check the [room version specification](/rooms) for version - check the [room version specification](/rooms) for
@ -154,22 +175,8 @@ paths:
The error should be passed through to clients so that they The error should be passed through to clients so that they
may give better feedback to users. may give better feedback to users.
The `M_MISSING_PARAM` error code is used to indicate one or more of If `M_MISSING_PARAM` or `M_INVALID_PARAM` is returned and the request is associated
the following: with a Client-Server API request, the Client-Server API request SHOULD fail
* The `m.room.create` event is missing from `invite_room_state`.
* One or more entries in `invite_room_state` are not formatted according
to the room's version.
* One or more events fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
* One or more events does not reside in the same room as the invite.
Note: Some room versions may require calculating the room ID for an
event rather than relying on the presence of `room_id`.
Servers MAY apply the validation above to room versions 1 through 11,
and SHOULD apply the validation above to all other room versions.
If `M_MISSING_PARAM` is returned and the request is associated with a
Client-Server API request, the Client-Server API request SHOULD fail
with a 5xx error rather than being passed through. with a 5xx error rather than being passed through.
content: content:
application/json: application/json:

178
data/api/server-server/joins-v1.yaml
View file

@ -23,6 +23,17 @@ paths:
description: |- description: |-
Asks the receiving server to return information that the sending Asks the receiving server to return information that the sending
server will need to prepare a join event to get into the room. server will need to prepare a join event to get into the room.
Before signing the returned template and calling `/send_join`,
the sending server MUST verify that:
* the `room_id` is equal to the `roomId` path parameter.
* both the `sender` and `state_key` are equal to the `userId` path parameter.
* the `type` of the event is `m.room.member`.
* the `membership` field inside `content` is `join`.
In case any of the above checks fail, the response MUST be treated as malformed and
discarded. The caller MAY try to join through another server.
operationId: makeJoin operationId: makeJoin
security: security:
- signedRequest: [] - signedRequest: []
@ -36,7 +47,7 @@ paths:
type: string type: string
- in: path - in: path
name: userId name: userId
description: The user ID the join event will be for. description: The user ID the join event will be for. This MUST be a user ID on the origin server.
required: true required: true
example: "@someone:example.org" example: "@someone:example.org"
schema: schema:
@ -223,171 +234,6 @@ paths:
"errcode": "M_NOT_FOUND", "errcode": "M_NOT_FOUND",
"error": "Unknown room" "error": "Unknown room"
} }
"/send_join/{roomId}/{eventId}":
put:
deprecated: true
summary: Submit a signed join event to a resident server
description: |-
**Note:**
Servers should instead prefer to use the v2 `/send_join` endpoint.
Submits a signed join event to the resident server for it
to accept it into the room's graph. Note that events have
a different format depending on the room version - check
the [room version specification](/rooms) for precise event formats.
**The request and response body here describe the common
event fields in more detail and may be missing other required
fields for a PDU.**
operationId: sendJoinV1
security:
- signedRequest: []
parameters:
- in: path
name: roomId
description: The room ID that is about to be joined.
required: true
example: "!abc123:matrix.org"
schema:
type: string
- in: path
name: eventId
description: The event ID for the join event.
required: true
example: $abc123:example.org
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
sender:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
origin:
type: string
description: The name of the joining homeserver.
example: matrix.org
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the joining homeserver.
example: 1234567890
type:
type: string
description: The value `m.room.member`.
example: m.room.member
state_key:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example:
membership: join
properties:
membership:
type: string
description: The value `join`.
example: join
join_authorised_via_users_server:
type: string
x-addedInMatrixVersion: "1.2"
description: |-
Required if the room is [restricted](/client-server-api/#restricted-rooms)
and is joining through one of the conditions available. If the
user is responding to an invite, this is not required.
An arbitrary user ID belonging to the resident server in
the room being joined that is able to issue invites to other
users. This is used in later validation of the auth rules for
the `m.room.member` event.
The resident server which owns the provided user ID must have a
valid signature on the event. If the resident server is receiving
the `/send_join` request, the signature must be added before sending
or persisting the event to other servers.
required:
- membership
required:
- state_key
- sender
- origin
- origin_server_ts
- type
- content
required: true
responses:
"200":
description: The join event has been accepted into the room.
content:
application/json:
schema:
type: array
minItems: 2
maxItems: 2
items:
anyOf:
- type: integer
description: The value `200`.
example: 200
- type: object
title: Room State
description: The state for the room.
properties:
auth_chain:
type: array
description: |-
The auth chain for the entire current room state prior to the join event.
Note that events have a different format depending on the room version - check the
[room version specification](/rooms) for precise event formats.
items:
type: object
title: PDU
description: |-
The [PDUs](/server-server-api/#pdus) that make up the auth chain. The event format varies depending
on the room version - check the [room version specification](/rooms) for precise event formats.
state:
type: array
description: |-
The resolved current room state prior to the join event.
The event format varies depending on the room version - check the [room version specification](/rooms)
for precise event formats.
items:
type: object
title: PDU
description: |-
The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format varies depending
on the room version - check the [room version specification](/rooms) for precise event formats.
required:
- auth_chain
- state
examples:
response:
value: [
200,
{
"auth_chain": [
{
"$ref": "examples/minimal_pdu.json"
}
],
"state": [
{
"$ref": "examples/minimal_pdu.json"
}
],
"event": {
"$ref": "examples/pdu_v4_join_membership.json"
}
}
]
servers: servers:
- url: "{protocol}://{hostname}{basePath}" - url: "{protocol}://{hostname}{basePath}"
variables: variables:

22
data/api/server-server/joins-v2.yaml
View file

@ -22,15 +22,6 @@ paths:
put: put:
summary: Submit a signed join event to a resident server summary: Submit a signed join event to a resident server
description: |- description: |-
**Note:**
This API is nearly identical to the v1 API with the
exception of the response format being fixed.
This endpoint is preferred over the v1 API as it provides
a more standardised response format. Senders which receive
a 400, 404, or other status code which indicates this endpoint
is not available should retry using the v1 API instead.
Submits a signed join event to the resident server for it Submits a signed join event to the resident server for it
to accept it into the room's graph. Note that events have to accept it into the room's graph. Note that events have
a different format depending on the room version - check a different format depending on the room version - check
@ -38,6 +29,15 @@ paths:
**The request and response body here describe the common **The request and response body here describe the common
event fields in more detail and may be missing other required event fields in more detail and may be missing other required
fields for a PDU.** fields for a PDU.**
The receiving server MUST apply certain validation before accepting the event.
A specific error code is not mandated, but servers SHOULD return `M_INVALID_PARAM` if:
* The join event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
* The event type is not `m.room.member`.
* The `membership` field inside the event content is not `join`.
* The event sender is not a user ID on the origin server.
* The `state_key` is not equal to the `sender`.
operationId: sendJoinV2 operationId: sendJoinV2
security: security:
- signedRequest: [] - signedRequest: []
@ -247,6 +247,10 @@ paths:
The error should be passed through to clients so that they The error should be passed through to clients so that they
may give better feedback to users. may give better feedback to users.
If `M_MISSING_PARAM` or `M_INVALID_PARAM` is returned and the request is associated
with a Client-Server API request, the Client-Server API request SHOULD fail
with a 5xx error rather than being passed through.
New in `v1.2`, the following error conditions might happen: New in `v1.2`, the following error conditions might happen:
If the room is [restricted](/client-server-api/#restricted-rooms) If the room is [restricted](/client-server-api/#restricted-rooms)

35
data/api/server-server/knocks.yaml
View file

@ -23,6 +23,17 @@ paths:
description: |- description: |-
Asks the receiving server to return information that the sending Asks the receiving server to return information that the sending
server will need to prepare a knock event for the room. server will need to prepare a knock event for the room.
Before signing the returned template and calling `/send_knock`,
the sending server MUST verify that:
* the `room_id` is equal to the `roomId` path parameter.
* both the `sender` and `state_key` are equal to the `userId` path parameter.
* the `type` of the event is `m.room.member`.
* the `membership` field inside `content` is `knock`.
In case any of the above checks fail, the response MUST be treated as malformed and
discarded. The caller MAY try to knock through another server.
operationId: makeKnock operationId: makeKnock
security: security:
- signedRequest: [] - signedRequest: []
@ -36,7 +47,7 @@ paths:
type: string type: string
- in: path - in: path
name: userId name: userId
description: The user ID the knock event will be for. description: The user ID the knock event will be for. This MUST be a user ID on the origin server.
required: true required: true
example: "@someone:example.org" example: "@someone:example.org"
schema: schema:
@ -204,6 +215,15 @@ paths:
**The request and response body here describe the common **The request and response body here describe the common
event fields in more detail and may be missing other required event fields in more detail and may be missing other required
fields for a PDU.** fields for a PDU.**
The receiving server MUST apply certain validation before accepting the event.
A specific error code is not mandated, but servers SHOULD return `M_INVALID_PARAM` if:
* The knock event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
* The event type is not `m.room.member`.
* The `membership` field inside the event content is not `knock`.
* The event sender is not a user ID on the origin server.
* The `state_key` is not equal to the `sender`.
operationId: sendKnock operationId: sendKnock
security: security:
- signedRequest: [] - signedRequest: []
@ -330,6 +350,19 @@ paths:
"$ref": "./examples/invite_or_knock_state.json" "$ref": "./examples/invite_or_knock_state.json"
} }
} }
"400":
description: |-
The request is invalid in some way.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_INVALID_PARAM",
"error": "Not a knock event."
}
"403": "403":
description: |- description: |-
The knocking server or user is not permitted to knock on the room, such as when the The knocking server or user is not permitted to knock on the room, such as when the

124
data/api/server-server/leaving-v1.yaml
View file

@ -23,6 +23,17 @@ paths:
description: |- description: |-
Asks the receiving server to return information that the sending Asks the receiving server to return information that the sending
server will need to prepare a leave event to get out of the room. server will need to prepare a leave event to get out of the room.
Before signing the returned template and calling `/send_leave`,
the sending server MUST verify that:
* the `room_id` is equal to the `roomId` path parameter.
* both the `sender` and `state_key` are equal to the `userId` path parameter.
* the `type` of the event is `m.room.member`.
* the `membership` field inside `content` is `leave`.
In case any of the above checks fail, the response MUST be treated as malformed and
discarded. The caller MAY try to leave through another server.
operationId: makeLeave operationId: makeLeave
security: security:
- signedRequest: [] - signedRequest: []
@ -36,7 +47,7 @@ paths:
type: string type: string
- in: path - in: path
name: userId name: userId
description: The user ID the leave event will be for. description: The user ID the leave event will be for. This MUST be a user ID on the origin server.
required: true required: true
example: "@someone:example.org" example: "@someone:example.org"
schema: schema:
@ -138,117 +149,6 @@ paths:
"errcode": "M_FORBIDDEN", "errcode": "M_FORBIDDEN",
"error": "User is not in the room." "error": "User is not in the room."
} }
"/send_leave/{roomId}/{eventId}":
put:
deprecated: true
summary: Submit a signed leave event to a resident server
description: |-
**Note:**
Servers should instead prefer to use the v2 `/send_leave` endpoint.
Submits a signed leave event to the resident server for it
to accept it into the room's graph. Note that events have
a different format depending on the room version - check
the [room version specification](/rooms) for precise event formats.
**The request and response body here describe the common
event fields in more detail and may be missing other required
fields for a PDU.**
operationId: sendLeaveV1
security:
- signedRequest: []
parameters:
- in: path
name: roomId
description: The room ID that is about to be left.
required: true
example: "!abc123:matrix.org"
schema:
type: string
- in: path
name: eventId
description: The event ID for the leave event.
required: true
example: $abc123:example.org
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
sender:
type: string
description: The user ID of the leaving member.
example: "@someone:example.org"
origin:
type: string
description: The name of the leaving homeserver.
example: matrix.org
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the leaving homeserver.
example: 1234567890
type:
type: string
description: The value `m.room.member`.
example: m.room.member
state_key:
type: string
description: The user ID of the leaving member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example:
membership: leave
properties:
membership:
type: string
description: The value `leave`.
example: leave
required:
- membership
depth:
type: integer
description: This field must be present but is ignored; it may be 0.
example: 12
required:
- state_key
- sender
- origin
- origin_server_ts
- type
- depth
- content
required: true
responses:
"200":
description: |-
An empty response to indicate the event was accepted into the graph by
the receiving homeserver.
content:
application/json:
schema:
type: array
minItems: 2
maxItems: 2
items:
anyOf:
- type: integer
description: The value `200`.
example: 200
- type: object
title: Empty Object
description: An empty object.
examples:
response:
value: [
200,
{}
]
servers: servers:
- url: "{protocol}://{hostname}{basePath}" - url: "{protocol}://{hostname}{basePath}"
variables: variables:

31
data/api/server-server/leaving-v2.yaml
View file

@ -22,15 +22,6 @@ paths:
put: put:
summary: Submit a signed leave event to a resident server summary: Submit a signed leave event to a resident server
description: |- description: |-
**Note:**
This API is nearly identical to the v1 API with the
exception of the response format being fixed.
This endpoint is preferred over the v1 API as it provides
a more standardised response format. Senders which receive
a 400, 404, or other status code which indicates this endpoint
is not available should retry using the v1 API instead.
Submits a signed leave event to the resident server for it Submits a signed leave event to the resident server for it
to accept it into the room's graph. Note that events have to accept it into the room's graph. Note that events have
a different format depending on the room version - check a different format depending on the room version - check
@ -38,6 +29,15 @@ paths:
**The request and response body here describe the common **The request and response body here describe the common
event fields in more detail and may be missing other required event fields in more detail and may be missing other required
fields for a PDU.** fields for a PDU.**
The receiving server MUST apply certain validation before accepting the event.
A specific error code is not mandated, but servers SHOULD return `M_INVALID_PARAM` if:
* The leave event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
* The event type is not `m.room.member`.
* The `membership` field inside the event content is not `leave`.
* The event sender is not a user ID on the origin server.
* The `state_key` is not equal to the `sender`.
operationId: sendLeaveV2 operationId: sendLeaveV2
security: security:
- signedRequest: [] - signedRequest: []
@ -134,6 +134,19 @@ paths:
examples: examples:
response: response:
value: {} value: {}
"400":
description: |-
The request is invalid in some way.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_INVALID_PARAM",
"error": "Not a leave event."
}
servers: servers:
- url: "{protocol}://{hostname}{basePath}" - url: "{protocol}://{hostname}{basePath}"
variables: variables:

4
data/api/server-server/public_rooms.yaml
View file

@ -49,7 +49,7 @@ paths:
name: include_all_networks name: include_all_networks
description: |- description: |-
Whether or not to include all networks/protocols defined by application Whether or not to include all networks/protocols defined by application
services on the homeserver. Defaults to false. services on the homeserver. Defaults to `false`.
example: false example: false
schema: schema:
type: boolean type: boolean
@ -121,7 +121,7 @@ paths:
type: boolean type: boolean
description: |- description: |-
Whether or not to include all known networks/protocols from Whether or not to include all known networks/protocols from
application services on the homeserver. Defaults to false. application services on the homeserver. Defaults to `false`.
example: false example: false
third_party_instance_id: third_party_instance_id:
type: string type: string

2
data/api/server-server/user_devices.yaml
View file

@ -79,7 +79,7 @@ paths:
- keys - keys
master_key: master_key:
type: object type: object
description: The user\'s master cross-signing key. description: The user\'s master signing key.
allOf: allOf:
- $ref: ../client-server/definitions/cross_signing_key.yaml - $ref: ../client-server/definitions/cross_signing_key.yaml
- example: - example:

4
data/api/server-server/user_keys.yaml
View file

@ -194,8 +194,8 @@ paths:
x-addedInMatrixVersion: "1.1" x-addedInMatrixVersion: "1.1"
type: object type: object
description: |- description: |-
Information on the master cross-signing keys of the queried users. Information on the master signing keys of the queried users.
A map from user ID, to master key information. For each key, the A map from user ID, to master signing key information. For each key, the
information returned will be the same as uploaded via information returned will be the same as uploaded via
`/keys/device_signing/upload`, along with the signatures `/keys/device_signing/upload`, along with the signatures
uploaded via `/keys/signatures/upload` that the user is uploaded via `/keys/signatures/upload` that the user is

3
data/event-schemas/schema/core-event-schema/event.yaml
View file

@ -7,8 +7,7 @@ properties:
When interacting with the REST API, this is the HTTP body. When interacting with the REST API, this is the HTTP body.
type: object type: object
type: type:
description: The type of event. This SHOULD be namespaced similar to Java package description: The type of event, as defined by [the event type specification](/client-server-api/#types-of-room-events).
naming conventions e.g. 'com.example.subdomain.event.type'
type: string type: string
required: required:
- type - type

2
data/event-schemas/schema/m.room.server_acl.yaml
View file

@ -54,7 +54,7 @@ properties:
type: boolean type: boolean
description: |- description: |-
True to allow server names that are IP address literals. False to True to allow server names that are IP address literals. False to
deny. Defaults to true if missing or otherwise not a boolean. deny. Defaults to `true` if missing or otherwise not a boolean.
This is strongly recommended to be set to `false` as servers running This is strongly recommended to be set to `false` as servers running
with IP literal names are strongly discouraged in order to require with IP literal names are strongly discouraged in order to require

2
layouts/_partials/events/render-event.html
View file

@ -49,7 +49,7 @@
</tr> </tr>
{{ if $state_key }} {{ if $state_key }}
<tr> <tr>
<th>State key</th> <th>State key:</th>
<td>{{ $state_key.description | markdownify }}</td> <td>{{ $state_key.description | markdownify }}</td>
</tr> </tr>
{{ end }} {{ end }}