wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Fix internal links

Browse source
This commit is contained in:
Will 2021-01-20 21:45:35 -08:00
parent 338434bfcd
commit 4e39200cfa
No known key found for this signature in database
GPG key ID: 385872BB265E8BF8
30 changed files with 194 additions and 792 deletions
Download patch file Download diff file Expand all files Collapse all files

24
content/_index.md
View file

@ -13,7 +13,7 @@ together existing communication silos - providing the basis of a new
open real-time communication ecosystem. open real-time communication ecosystem.
To propose a change to the Matrix Spec, see the explanations at To propose a change to the Matrix Spec, see the explanations at
[Proposals for Spec Changes to Matrix](proposals). [Proposals for Spec Changes to Matrix](/proposals).
## Matrix APIs ## Matrix APIs
@ -26,7 +26,7 @@ information required to understand the specific APIs, including the
sections on [room versions](#room-versions) and [overall sections on [room versions](#room-versions) and [overall
architecture](#architecture). architecture](#architecture).
The [Appendices](appendices.html) contain supplemental information not The [Appendices](/appendices) contain supplemental information not
specific to one of the above APIs. specific to one of the above APIs.
The [Matrix Client-Server API Swagger The [Matrix Client-Server API Swagger
@ -123,7 +123,7 @@ an interoperable and federated manner.
### Spec Change Proposals ### Spec Change Proposals
To propose a change to the Matrix Spec, see the explanations at To propose a change to the Matrix Spec, see the explanations at
[Proposals for Spec Changes to Matrix](proposals). [Proposals for Spec Changes to Matrix](/proposals).
## Architecture ## Architecture
@ -184,7 +184,7 @@ which allocated the account and has the form:
@localpart:domain @localpart:domain
See ['Identifier Grammar' in the See ['Identifier Grammar' in the
appendices](appendices.html#identifier-grammar) for full details of the appendices](/appendices#identifier-grammar) for full details of the
structure of user IDs. structure of user IDs.
### Devices ### Devices
@ -266,7 +266,7 @@ contain a domain, it is simply for globally namespacing room IDs. The
room does NOT reside on the domain specified. room does NOT reside on the domain specified.
See ['Identifier Grammar' in the See ['Identifier Grammar' in the
appendices](appendices.html#identifier-grammar) for full details of the appendices](/appendices#identifier-grammar) for full details of the
structure of a room ID. structure of a room ID.
The following conceptual diagram shows an `m.room.message` event being The following conceptual diagram shows an `m.room.message` event being
@ -350,7 +350,7 @@ Each room can also have multiple "Room Aliases", which look like:
#room_alias:domain #room_alias:domain
See ['Identifier Grammar' in the See ['Identifier Grammar' in the
appendices](appendices.html#identifier-grammar) for full details of the appendices](/appendices#identifier-grammar) for full details of the
structure of a room alias. structure of a room alias.
A room alias "points" to a room ID and is the human-readable label by A room alias "points" to a room ID and is the human-readable label by
@ -494,17 +494,17 @@ the default room version when creating new rooms.
The available room versions are: The available room versions are:
- [Version 1](rooms/v1.html) - **Stable**. The current version of most - [Version 1](/rooms/v1) - **Stable**. The current version of most
rooms. rooms.
- [Version 2](rooms/v2.html) - **Stable**. Implements State Resolution - [Version 2](/rooms/v2) - **Stable**. Implements State Resolution
Version 2. Version 2.
- [Version 3](rooms/v3.html) - **Stable**. Introduces events whose IDs - [Version 3](/rooms/v3) - **Stable**. Introduces events whose IDs
are the event's hash. are the event's hash.
- [Version 4](rooms/v4.html) - **Stable**. Builds on v3 by using - [Version 4](/rooms/v4) - **Stable**. Builds on v3 by using
URL-safe base64 for event IDs. URL-safe base64 for event IDs.
- [Version 5](rooms/v5.html) - **Stable**. Introduces enforcement of - [Version 5](/rooms/v5) - **Stable**. Introduces enforcement of
signing key validity periods. signing key validity periods.
- [Version 6](rooms/v6.html) - **Stable**. Alters several - [Version 6](/rooms/v6) - **Stable**. Alters several
authorization rules for events. authorization rules for events.
## Specification Versions ## Specification Versions

8
content/appendices.md
View file

@ -284,7 +284,7 @@ The following canonical JSON should be produced:
JSON is signed by encoding the JSON object without `signatures` or keys JSON is signed by encoding the JSON object without `signatures` or keys
grouped as `unsigned`, using the canonical encoding described above. The grouped as `unsigned`, using the canonical encoding described above. The
JSON bytes are then signed using the signature algorithm and the JSON bytes are then signed using the signature algorithm and the
signature is encoded using [unpadded Base64](). The resulting base64 signature is encoded using [unpadded Base64](#unpadded-base64). The resulting base64
signature is added to an object under the *signing key identifier* which signature is added to an object under the *signing key identifier* which
is added to the `signatures` object under the name of the entity signing is added to the `signatures` object under the name of the entity signing
it which is added back to the original JSON object along with the it which is added back to the original JSON object along with the
@ -363,7 +363,7 @@ the following:
## Identifier Grammar ## Identifier Grammar
Some identifiers are specific to given room versions, please refer to Some identifiers are specific to given room versions, please refer to
the [room versions specification](index.html#room-versions) for more the [room versions specification](/#room-versions) for more
information. information.
### Server Name ### Server Name
@ -578,7 +578,7 @@ A room has exactly one room ID. A room ID has the format:
!opaque_id:domain !opaque_id:domain
An event has exactly one event ID. The format of an event ID depends An event has exactly one event ID. The format of an event ID depends
upon the [room version specification](index.html#room-versions). upon the [room version specification](/#room-versions).
The `domain` of a room ID is the [server name](#server-name) of the The `domain` of a room ID is the [server name](#server-name) of the
homeserver which created the room/event. The domain is used only for homeserver which created the room/event. The domain is used only for
@ -686,7 +686,7 @@ the client if possible.
{{% boxes/note %}} {{% boxes/note %}}
Clients should be aware that decoding a matrix.to URI may result in Clients should be aware that decoding a matrix.to URI may result in
extra slashes appearing due to some [room extra slashes appearing due to some [room
versions](index.html#room-versions). These slashes should normally be versions](/#room-versions). These slashes should normally be
encoded when producing matrix.to URIs, however. encoded when producing matrix.to URIs, however.
{{% /boxes/note %}} {{% /boxes/note %}}

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

@ -298,7 +298,7 @@ conscientious decision what to do next.
{{% boxes/note %}} {{% boxes/note %}}
Servers hosting the `.well-known` JSON file SHOULD offer CORS headers, Servers hosting the `.well-known` JSON file SHOULD offer CORS headers,
as per the [CORS](#CORS) section in this specification. as per the [CORS](#web-browser-clients) section in this specification.
{{% /boxes/note %}} {{% /boxes/note %}}
The `.well-known` method uses a JSON file at a predetermined location to The `.well-known` method uses a JSON file at a predetermined location to
@ -342,7 +342,7 @@ Most API endpoints require the user to identify themselves by presenting
previously obtained credentials in the form of an `access_token` query previously obtained credentials in the form of an `access_token` query
parameter or through an Authorization Header of `Bearer $access_token`. parameter or through an Authorization Header of `Bearer $access_token`.
An access token is typically obtained via the [Login](#login) or An access token is typically obtained via the [Login](#login) or
[Registration](#Registration) processes. [Registration](#account-registration-and-management) processes.
{{% boxes/note %}} {{% boxes/note %}}
This specification does not mandate a particular format for the access This specification does not mandate a particular format for the access
@ -374,7 +374,7 @@ Client [devices](../index.html#devices) are closely related to access
tokens. Matrix servers should record which device each access token is tokens. Matrix servers should record which device each access token is
assigned to, so that subsequent requests can be handled correctly. assigned to, so that subsequent requests can be handled correctly.
By default, the [Login](#login) and [Registration](#Registration) By default, the [Login](#login) and [Registration](#account-registration-and-management)
processes auto-generate a new `device_id`. A client is also free to processes auto-generate a new `device_id`. A client is also free to
generate its own `device_id` or, provided the user remains the same, generate its own `device_id` or, provided the user remains the same,
reuse a device: in either case the client should pass the `device_id` in reuse a device: in either case the client should pass the `device_id` in
@ -732,7 +732,7 @@ sign-on provider.
A client wanting to complete authentication using SSO should use the A client wanting to complete authentication using SSO should use the
[Fallback](#fallback) mechanism. See [SSO during User-Interactive [Fallback](#fallback) mechanism. See [SSO during User-Interactive
Authentication]() for more information. Authentication](#sso-during-user-interactive-authentication) for more information.
#### Email-based (identity / homeserver) #### Email-based (identity / homeserver)
@ -970,7 +970,7 @@ form.
A client can identify a user using a 3PID associated with the user's A client can identify a user using a 3PID associated with the user's
account on the homeserver, where the 3PID was previously associated account on the homeserver, where the 3PID was previously associated
using the `/account/3pid`\_ API. See the [3PID using the `/account/3pid`\_ API. See the [3PID
Types](../appendices.html#pid-types) Appendix for a list of Third-party Types](/appendices#3pid-types) Appendix for a list of Third-party
ID media. ID media.
```json ```json
@ -1065,7 +1065,7 @@ respond with `403 Forbidden` and an error code of `M_FORBIDDEN`.
If the homeserver advertises `m.login.sso` as a viable flow, and the If the homeserver advertises `m.login.sso` as a viable flow, and the
client supports it, the client should redirect the user to the client supports it, the client should redirect the user to the
`/redirect` endpoint for [client login via SSO](). After authentication `/redirect` endpoint for [client login via SSO](#client-login-via-sso). After authentication
is complete, the client will need to submit a `/login` request matching is complete, the client will need to submit a `/login` request matching
`m.login.token`. `m.login.token`.
@ -1504,9 +1504,9 @@ following fields.
The complete event MUST NOT be larger than 65535 bytes, when formatted The complete event MUST NOT be larger than 65535 bytes, when formatted
as a [PDU for the Server-Server as a [PDU for the Server-Server
protocol](../server_server/%SERVER_RELEASE_LABEL%#pdus), including any protocol](/server-server-api/#pdus), including any
signatures, and encoded as [Canonical signatures, and encoded as [Canonical
JSON](../appendices.html#canonical-json). JSON](/appendices#canonical-json).
There are additional restrictions on sizes per key: There are additional restrictions on sizes per key:
@ -1821,7 +1821,7 @@ of user B to a maximum of level 50. Power levels for users are tracked
per-room even if the user is not present in the room. The keys contained per-room even if the user is not present in the room. The keys contained
in `m.room.power_levels` determine the levels required for certain in `m.room.power_levels` determine the levels required for certain
operations such as kicking, banning and sending state events. See operations such as kicking, banning and sending state events. See
[m.room.power\_levels]() for more information. [m.room.power\_levels](#room-events) for more information.
Clients may wish to assign names to particular power levels. A suggested Clients may wish to assign names to particular power levels. A suggested
mapping is as follows: - 0 User - 50 Moderator - 100 Admin mapping is as follows: - 0 User - 50 Moderator - 100 Admin
@ -2043,620 +2043,38 @@ that profile.
#### Summary #### Summary
<table> | Module / Profile | Web | Mobile | Desktop | CLI | Embedded |
<thead> |------------------------------------------------------------|-----------|----------|----------|----------|----------|
<tr class="header"> | [Instant Messaging](#instant-messaging) | Required | Required | Required | Required | Optional |
<th>Module / Profile</th> | [Direct Messaging](#direct-messaging) | Required | Required | Required | Required | Optional |
<th>Web</th> | [Mentions](#user-room-and-group-mentions) | Required | Required | Required | Optional | Optional |
<th>Mobile</th> | [Presence](#presence) | Required | Required | Required | Required | Optional |
<th>Desktop</th> | [Push Notifications](#push-notifications) | Optional | Required | Optional | Optional | Optional |
<th>CLI</th> | [Receipts](#receipts) | Required | Required | Required | Required | Optional |
<th>Embedded</th> | [Fully read markers](#fully-read-markers) | Optional | Optional | Optional | Optional | Optional |
</tr> | [Typing Notifications](#typing-notifications) | Required | Required | Required | Required | Optional |
</thead> | [VoIP](#voice-over-ip) | Required | Required | Required | Optional | Optional |
<tbody> | [Ignoring Users](#ignoring-users) | Required | Required | Required | Optional | Optional |
<tr class="odd"> | [Reporting Content](#reporting-content) | Optional | Optional | Optional | Optional | Optional |
<td><blockquote> | [Content Repository](#content-repository) | Required | Required | Required | Optional | Optional |
<p><a href="">Instant Messaging</a></p> | [Managing History Visibility](#room-history-visibility) | Required | Required | Required | Required | Optional |
</blockquote></td> | [Server Side Search](#server-side-search) | Optional | Optional | Optional | Optional | Optional |
<td><blockquote> | [Room Upgrades](#room-upgrades) | Required | Required | Required | Required | Optional |
<p>Required</p> | [Server Administration](#server-administration) | Optional | Optional | Optional | Optional | Optional |
</blockquote></td> | [Event Context](#event-context) | Optional | Optional | Optional | Optional | Optional |
<td><blockquote> | [Third Party Networks](#third-party-networks) | Optional | Optional | Optional | Optional | Optional |
<p>Required</p> | [Send-to-Device Messaging](#send-to-device-messaging) | Optional | Optional | Optional | Optional | Optional |
</blockquote></td> | [Device Management](#device-management) | Optional | Optional | Optional | Optional | Optional |
<td><blockquote> | [End-to-End Encryption](#end-to-end-encryption) | Optional | Optional | Optional | Optional | Optional |
<p>Required</p> | [Guest Accounts](#guest-access) | Optional | Optional | Optional | Optional | Optional |
</blockquote></td> | [Room Previews](#room-previews) | Optional | Optional | Optional | Optional | Optional |
<td><blockquote> | [Client Config](#client-config) | Optional | Optional | Optional | Optional | Optional |
<p>Required</p> | [SSO Login](#sso-client-loginauthentication) | Optional | Optional | Optional | Optional | Optional |
</blockquote></td> | [OpenID](#openid) | Optional | Optional | Optional | Optional | Optional |
<td><blockquote> | [Stickers](#sticker-messages) | Optional | Optional | Optional | Optional | Optional |
<p>Optional</p> | [Server ACLs](#server-access-control-lists-acls-for-rooms) | Optional | Optional | Optional | Optional | Optional |
</blockquote></td> | [Server Notices](#server-notices) | Optional | Optional | Optional | Optional | Optional |
</tr> | [Moderation policies](#moderation-policy-lists) | Optional | Optional | Optional | Optional | Optional |
<tr class="even">
<td><blockquote>
<p><a href="">Direct Messaging</a></p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
<tr class="odd">
<td><blockquote>
<p><a href="">Mentions</a></p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
<tr class="even">
<td><blockquote>
<p><a href="">Presence</a></p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
<tr class="odd">
<td><blockquote>
<p><a href="">Push Notifications</a></p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
<tr class="even">
<td><blockquote>
<p><a href="">Receipts</a></p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
<tr class="odd">
<td><blockquote>
<p><a href="">Fully read markers</a></p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
<tr class="even">
<td><blockquote>
<p><a href="">Typing Notifications</a></p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
<tr class="odd">
<td><blockquote>
<p><a href="">VoIP</a></p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
<tr class="even">
<td><blockquote>
<p><a href="">Ignoring Users</a></p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
<tr class="odd">
<td><blockquote>
<p><a href="">Reporting Content</a></p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
<tr class="even">
<td><blockquote>
<p><a href="">Content Repository</a></p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
<tr class="odd">
<td><blockquote>
<p><a href="">Managing History Visibility</a></p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
<tr class="even">
<td><blockquote>
<p><a href="">Server Side Search</a></p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
<tr class="odd">
<td><blockquote>
<p><a href="">Room Upgrades</a></p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Required</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
<tr class="even">
<td><blockquote>
<p><a href="">Server Administration</a></p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
<tr class="odd">
<td><blockquote>
<p><a href="">Event Context</a></p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
<tr class="even">
<td><blockquote>
<p><a href="">Third Party Networks</a></p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
<tr class="odd">
<td><blockquote>
<p><a href="">Send-to-Device Messaging</a></p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
<tr class="even">
<td><blockquote>
<p><a href="">Device Management</a></p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
<tr class="odd">
<td><blockquote>
<p><a href="">End-to-End Encryption</a></p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
<tr class="even">
<td><blockquote>
<p><a href="">Guest Accounts</a></p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
<tr class="odd">
<td><blockquote>
<p><a href="">Room Previews</a></p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
<tr class="even">
<td><blockquote>
<p><a href="">Client Config</a></p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
<tr class="odd">
<td><blockquote>
<p><a href="">SSO Login</a></p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
<tr class="even">
<td><blockquote>
<p><a href="">OpenID</a></p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
<tr class="odd">
<td><blockquote>
<p><a href="">Stickers</a></p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
<tr class="even">
<td><blockquote>
<p><a href="">Server ACLs</a></p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
<tr class="odd">
<td><blockquote>
<p><a href="">Server Notices</a></p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
<tr class="even">
<td><blockquote>
<p><a href="">Moderation policies</a></p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
<td><blockquote>
<p>Optional</p>
</blockquote></td>
</tr>
</tbody>
</table>
*Please see each module for more details on what clients need to *Please see each module for more details on what clients need to
implement.* implement.*

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

@ -29,4 +29,4 @@ These events can also be received in a `/events` response or in the
Servers MUST reject clients from setting account data for event types Servers MUST reject clients from setting account data for event types
that the server manages. Currently, this only includes that the server manages. Currently, this only includes
[m.fully\_read](). [m.fully\_read](#mfully_read).

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

@ -5,7 +5,7 @@ weight: 90
### Device Management ### Device Management
This module provides a means for a user to manage their [devices](). This module provides a means for a user to manage their [devices](/#devices).
#### Client behaviour #### Client behaviour

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

@ -32,7 +32,7 @@ a person's profile picture would imply the `is_direct` flag should be
set. set.
The invitee's client may use the `is_direct` flag in the The invitee's client may use the `is_direct` flag in the
[m.room.member]() event to automatically mark the room as a direct chat [m.room.member](#mroommember) event to automatically mark the room as a direct chat
but this is not required: it may for example, prompt the user, or ignore but this is not required: it may for example, prompt the user, or ignore
the flag altogether. the flag altogether.

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

@ -57,13 +57,13 @@ keys.
The name `ed25519` corresponds to the The name `ed25519` corresponds to the
[Ed25519](http://ed25519.cr.yp.to/) signature algorithm. The key is a [Ed25519](http://ed25519.cr.yp.to/) signature algorithm. The key is a
32-byte Ed25519 public key, encoded using [unpadded Base64](). Example: 32-byte Ed25519 public key, encoded using [unpadded Base64](/appendices/#unpadded-base64). Example:
"SogYyrkTldLz0BXP+GYWs0qaYacUI0RleEqNT8J3riQ" "SogYyrkTldLz0BXP+GYWs0qaYacUI0RleEqNT8J3riQ"
The name `curve25519` corresponds to the The name `curve25519` corresponds to the
[Curve25519](https://cr.yp.to/ecdh.html) ECDH algorithm. The key is a [Curve25519](https://cr.yp.to/ecdh.html) ECDH algorithm. The key is a
32-byte Curve25519 public key, encoded using [unpadded Base64](). 32-byte Curve25519 public key, encoded using [unpadded Base64](/appendices/#unpadded-base64).
Example: Example:
"JGLn/yafz74HB2AbPLYJWIVGnKAtqECOBf11yyXac2Y" "JGLn/yafz74HB2AbPLYJWIVGnKAtqECOBf11yyXac2Y"
@ -92,7 +92,7 @@ with the following properties:
<td><p>signatures</p></td> <td><p>signatures</p></td>
<td><p>Signatures</p></td> <td><p>Signatures</p></td>
<td><p><strong>Required.</strong> Signatures of the key object.</p> <td><p><strong>Required.</strong> Signatures of the key object.</p>
<p>The signature is calculated using the process described at <a href="../appendices.html#signing-json">Signing JSON</a>.</p></td> <p>The signature is calculated using the process described at <a href="/appendices/#signing-json">Signing JSON</a>.</p></td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
@ -134,7 +134,7 @@ A device uploads the public parts of identity keys to their homeserver
as a signed JSON object, using the `/keys/upload`\_ API. The JSON object as a signed JSON object, using the `/keys/upload`\_ API. The JSON object
must include the public part of the device's Ed25519 key, and must be must include the public part of the device's Ed25519 key, and must be
signed by that key, as described in [Signing signed by that key, as described in [Signing
JSON](../appendices.html#signing-json). JSON](/appendices/#signing-json).
One-time keys are also uploaded to the homeserver using the One-time keys are also uploaded to the homeserver using the
`/keys/upload`\_ API. `/keys/upload`\_ API.
@ -270,7 +270,7 @@ Extensions to `m.room.message` msgtypes
This module adds `file` and `thumbnail_file` properties, of type This module adds `file` and `thumbnail_file` properties, of type
`EncryptedFile`, to `m.room.message` msgtypes that reference files, such `EncryptedFile`, to `m.room.message` msgtypes that reference files, such
as [m.file]() and [m.image](), replacing the `url` and `thumbnail_url` as [m.file](#mfile) and [m.image](#mimage), replacing the `url` and `thumbnail_url`
properties. properties.
`EncryptedFile` `EncryptedFile`
@ -508,7 +508,7 @@ example, if we verify 40 bits, then an attacker has a 1 in
success. A failed attack would result in a mismatched Short success. A failed attack would result in a mismatched Short
Authentication String, alerting users to the attack. Authentication String, alerting users to the attack.
The verification process takes place over [to-device]() messages in two The verification process takes place over [to-device](#send-to-device-messaging) messages in two
phases: phases:
1. Key agreement phase (based on [ZRTP key 1. Key agreement phase (based on [ZRTP key
@ -566,7 +566,7 @@ The process between Alice and Bob verifying each other would be:
hash function. HMAC is defined in [RFC hash function. HMAC is defined in [RFC
2104](https://tools.ietf.org/html/rfc2104). The key for the HMAC is 2104](https://tools.ietf.org/html/rfc2104). The key for the HMAC is
different for each item and is calculated by generating 32 bytes different for each item and is calculated by generating 32 bytes
(256 bits) using [the key verification HKDF](#sas-hkdf). (256 bits) using [the key verification HKDF](#hkdf-calculation).
18. Alice's device sends Bob's device an `m.key.verification.mac` 18. Alice's device sends Bob's device an `m.key.verification.mac`
message containing the MAC of Alice's device keys and the MAC of her message containing the MAC of Alice's device keys and the MAC of her
key IDs to be verified. Bob's device does the same for Bob's device key IDs to be verified. Bob's device does the same for Bob's device
@ -721,7 +721,7 @@ parameter is the concatenation of:
###### SAS method: `decimal` ###### SAS method: `decimal`
Generate 5 bytes using [HKDF](#sas-hkdf) then take sequences of 13 bits Generate 5 bytes using [HKDF](#hkdf-calculation) then take sequences of 13 bits
to convert to decimal numbers (resulting in 3 numbers between 0 and 8191 to convert to decimal numbers (resulting in 3 numbers between 0 and 8191
inclusive each). Add 1000 to each calculated number. inclusive each). Add 1000 to each calculated number.
@ -739,7 +739,7 @@ separator, such as dashes, or with the numbers on individual lines.
###### SAS method: `emoji` ###### SAS method: `emoji`
Generate 6 bytes using [HKDF](#sas-hkdf) then split the first 42 bits Generate 6 bytes using [HKDF](#hkdf-calculation) then split the first 42 bits
into 7 groups of 6 bits, similar to how one would base64 encode into 7 groups of 6 bits, similar to how one would base64 encode
something. Convert each group of 6 bits to a number and use the something. Convert each group of 6 bits to a number and use the
following table to get the corresponding emoji: following table to get the corresponding emoji:
@ -933,20 +933,20 @@ device to another.
##### Key requests ##### Key requests
When a device is missing keys to decrypt messages, it can request the When a device is missing keys to decrypt messages, it can request the
keys by sending [m.room\_key\_request]() to-device messages to other keys by sending [m.room\_key\_request](#mroom_key_request) to-device messages to other
devices with `action` set to `request`. devices with `action` set to `request`.
If a device wishes to share the keys with that device, it can forward If a device wishes to share the keys with that device, it can forward
the keys to the first device by sending an encrypted the keys to the first device by sending an encrypted
[m.forwarded\_room\_key]() to-device message. The first device should [m.forwarded\_room\_key](#mforwarded_room_key) to-device message. The first device should
then send an [m.room\_key\_request]() to-device message with `action` then send an [m.room\_key\_request](#mroom_key_request) to-device message with `action`
set to `request_cancellation` to the other devices that it had set to `request_cancellation` to the other devices that it had
originally sent the key request to; a device that receives a originally sent the key request to; a device that receives a
`request_cancellation` should disregard any previously-received `request_cancellation` should disregard any previously-received
`request` message with the same `request_id` and `requesting_device_id`. `request` message with the same `request_id` and `requesting_device_id`.
If a device does not wish to share keys with that device, it can If a device does not wish to share keys with that device, it can
indicate this by sending an [m.room\_key.withheld]() to-device message, indicate this by sending an [m.room\_key.withheld](#mroom_key.withheld) to-device message,
as described in [Reporting that decryption keys are as described in [Reporting that decryption keys are
withheld](#reporting-that-decryption-keys-are-withheld). withheld](#reporting-that-decryption-keys-are-withheld).
@ -969,17 +969,17 @@ However, as the session keys are stored on the server encrypted, it
requires users to enter a decryption key to decrypt the session keys. requires users to enter a decryption key to decrypt the session keys.
To create a backup, a client will call [POST To create a backup, a client will call [POST
/\_matrix/client/r0/room\_keys/version]() and define how the keys are to /\_matrix/client/r0/room\_keys/version](#post_matrixclientr0room_keysversion) and define how the keys are to
be encrypted through the backup's `auth_data`; other clients can be encrypted through the backup's `auth_data`; other clients can
discover the backup by calling [GET discover the backup by calling [GET
/\_matrix/client/r0/room\_keys/version](). Keys are encrypted according /\_matrix/client/r0/room\_keys/version](#get_matrixclientr0room_keysversion). Keys are encrypted according
to the backup's `auth_data` and added to the backup by calling [PUT to the backup's `auth_data` and added to the backup by calling [PUT
/\_matrix/client/r0/room\_keys/keys]() or one of its variants, and can /\_matrix/client/r0/room\_keys/keys]() or one of its variants, and can
be retrieved by calling [GET /\_matrix/client/r0/room\_keys/keys]() or be retrieved by calling [GET /\_matrix/client/r0/room\_keys/keys](#put_matrixclientr0room_keyskeys) or
one of its variants. Keys can only be written to the most recently one of its variants. Keys can only be written to the most recently
created version of the backup. Backups can also be deleted using [DELETE created version of the backup. Backups can also be deleted using [DELETE
/\_matrix/client/r0/room\_keys/version/{version}](), or individual keys /\_matrix/client/r0/room\_keys/version/{version}](#delete_matrixclientr0room_keysversionversion), or individual keys
can be deleted using [DELETE /\_matrix/client/r0/room\_keys/keys]() or can be deleted using [DELETE /\_matrix/client/r0/room\_keys/keys](#delete_matrixclientr0room_keyskeys) or
one of its variants. 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
@ -1071,7 +1071,7 @@ The `session_data` field in the backups is constructed as follows:
<tr class="even"> <tr class="even">
<td><p>forwarding_curve25519_key_chain</p></td> <td><p>forwarding_curve25519_key_chain</p></td>
<td><p>[string]</p></td> <td><p>[string]</p></td>
<td><p><strong>Required.</strong> Chain of Curve25519 keys through which this session was forwarded, via <a href="">m.forwarded_room_key</a> events.</p></td> <td><p><strong>Required.</strong> Chain of Curve25519 keys through which this session was forwarded, via <a href="#mforwarded_room_key">m.forwarded_room_key</a> events.</p></td>
</tr> </tr>
<tr class="odd"> <tr class="odd">
<td><p>sender_key</p></td> <td><p>sender_key</p></td>
@ -1205,7 +1205,7 @@ objects described as follows:
<tr class="even"> <tr class="even">
<td><p>forwarding_curve25519_key_chain</p></td> <td><p>forwarding_curve25519_key_chain</p></td>
<td><p>[string]</p></td> <td><p>[string]</p></td>
<td><p>Required. Chain of Curve25519 keys through which this session was forwarded, via <a href="">m.forwarded_room_key</a> events.</p></td> <td><p>Required. Chain of Curve25519 keys through which this session was forwarded, via <a href="#mforwarded_room_key">m.forwarded_room_key</a> events.</p></td>
</tr> </tr>
<tr class="odd"> <tr class="odd">
<td><p>room_id</p></td> <td><p>room_id</p></td>
@ -1396,7 +1396,7 @@ a way to recover from the failure, making this session replacement
process required. process required.
{{% /boxes/note %}} {{% /boxes/note %}}
To establish a new session, the client sends an [m.dummy](#m-dummy) To establish a new session, the client sends an [m.dummy](#mdummy)
to-device event to the other party to notify them of the new session to-device event to the other party to notify them of the new session
details. details.

59
content/client-server-api/modules/guest_access.md
View file

@ -12,7 +12,7 @@ should interact with servers in order to participate in rooms as guests.
Guest users retrieve access tokens from a homeserver using the ordinary Guest users retrieve access tokens from a homeserver using the ordinary
[register [register
endpoint](#post-matrix-client-%CLIENT_MAJOR_VERSION%-register), endpoint](#post_matrixclientr0register),
specifying the `kind` parameter as `guest`. They may then interact with specifying the `kind` parameter as `guest`. They may then interact with
the client-server API as any other user would, but will only have access the client-server API as any other user would, but will only have access
to a subset of the API as described the Client behaviour subsection to a subset of the API as described the Client behaviour subsection
@ -39,55 +39,38 @@ rather than allowing all homeservers to enforce the rules on each other.
The following API endpoints are allowed to be accessed by guest accounts The following API endpoints are allowed to be accessed by guest accounts
for retrieving events: for retrieving events:
- [GET - [GET /rooms/:room\_id/state](#get_matrixclientr0roomsroomidstate)
/rooms/:room\_id/state](#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-state) - [GET /rooms/:room\_id/context/:event\_id](#get_matrixclientr0roomsroomidcontexteventid)
- [GET - [GET /rooms/:room\_id/event/:event\_id](#get_matrixclientr0roomsroomideventeventid)
/rooms/:room\_id/context/:event\_id](#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-context-eventid) - [GET /rooms/:room\_id/state/:event\_type/:state\_key](#get_matrixclientr0roomsroomidstateeventtypestatekey)
- [GET - [GET /rooms/:room\_id/messages](#get_matrixclientr0roomsroomidmessages)
/rooms/:room\_id/event/:event\_id](#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-event-eventid) - [GET /rooms/:room\_id/members](#get_matrixclientr0roomsroomidmembers)
- [GET - [GET /rooms/:room\_id/initialSync](#get_matrixclientr0roomsroomidinitialsync)
/rooms/:room\_id/state/:event\_type/:state\_key](#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-state-eventtype-statekey) - [GET /sync](#get_matrixclientr0sync)
- [GET - [GET /events](#get_matrixclientr0events) as used for room previews.
/rooms/:room\_id/messages](#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-messages)
- [GET
/rooms/:room\_id/members](#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-members)
- [GET
/rooms/:room\_id/initialSync](#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-initialsync)
- [GET /sync](#get-matrix-client-%CLIENT_MAJOR_VERSION%-sync)
- [GET /events]() as used for room previews.
The following API endpoints are allowed to be accessed by guest accounts The following API endpoints are allowed to be accessed by guest accounts
for sending events: for sending events:
- [POST - [POST /rooms/:room\_id/join](#post_matrixclientr0roomsroomidjoin)
/rooms/:room\_id/join](#post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-join) - [POST /rooms/:room\_id/leave](#post_matrixclientr0roomsroomidleave)
- [POST - [PUT /rooms/:room\_id/send/m.room.message/:txn\_id](#put_matrixclientr0roomsroomidsendeventtypetxnid)
/rooms/:room\_id/leave](#post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-leave) - [PUT /sendToDevice/{eventType}/{txnId}](#put_matrixclientr0sendtodeviceeventtypetxnid)
- [PUT
/rooms/:room\_id/send/m.room.message/:txn\_id](#put-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-send-eventtype-txnid)
- [PUT
/sendToDevice/{eventType}/{txnId}](#put-matrix-client-%CLIENT_MAJOR_VERSION%-sendtodevice-eventtype-txnid)
The following API endpoints are allowed to be accessed by guest accounts The following API endpoints are allowed to be accessed by guest accounts
for their own account maintenance: for their own account maintenance:
- [PUT - [PUT /profile/:user\_id/displayname](#put_matrixclientr0profileuseriddisplayname)
/profile/:user\_id/displayname](#put-matrix-client-%CLIENT_MAJOR_VERSION%-profile-userid-displayname) - [GET /devices](#get_matrixclientr0devices)
- [GET /devices](#get-matrix-client-%CLIENT_MAJOR_VERSION%-devices) - [GET /devices/{deviceId}](#get_matrixclientr0devicesdeviceid)
- [GET - [PUT /devices/{deviceId}](#put_matrixclientr0devicesdeviceid)
/devices/{deviceId}](#get-matrix-client-%CLIENT_MAJOR_VERSION%-devices-deviceid)
- [PUT
/devices/{deviceId}](#put-matrix-client-%CLIENT_MAJOR_VERSION%-devices-deviceid)
The following API endpoints are allowed to be accessed by guest accounts The following API endpoints are allowed to be accessed by guest accounts
for end-to-end encryption: for end-to-end encryption:
- [POST - [POST /keys/upload](#post_matrixclientr0keysupload)
/keys/upload](#post-matrix-client-%CLIENT_MAJOR_VERSION%-keys-upload) - [POST /keys/query](#post_matrixclientr0keysquery)
- [POST - [POST /keys/claim](#post_matrixclientr0keysclaim)
/keys/query](#post-matrix-client-%CLIENT_MAJOR_VERSION%-keys-query)
- [POST
/keys/claim](#post-matrix-client-%CLIENT_MAJOR_VERSION%-keys-claim)
#### Server behaviour #### Server behaviour

23
content/client-server-api/modules/instant_messaging.md
View file

@ -18,7 +18,7 @@ room itself such as a room name and topic.
Usage of this event is discouraged for several reasons: Usage of this event is discouraged for several reasons:
- The number of feedback events will grow very quickly with the number - The number of feedback events will grow very quickly with the number
of users in the room. This event provides no way to "batch" of users in the room. This event provides no way to "batch"
feedback, unlike the [receipts module](). feedback, unlike the [receipts module](#receipts).
- Pairing feedback to messages gets complicated when paginating as - Pairing feedback to messages gets complicated when paginating as
feedback arrives before the message it is acknowledging. feedback arrives before the message it is acknowledging.
- There are no guarantees that the client has seen the event ID being - There are no guarantees that the client has seen the event ID being
@ -34,7 +34,7 @@ Usage of this event is discouraged for several reasons:
##### m.room.message msgtypes ##### m.room.message msgtypes
Each [m.room.message]() MUST have a `msgtype` key which identifies the Each [m.room.message](#m.room.message) MUST have a `msgtype` key which identifies the
type of message being sent. Each type has their own required and type of message being sent. Each type has their own required and
optional keys, as outlined below. If a client cannot display the given optional keys, as outlined below. If a client cannot display the given
`msgtype` then it SHOULD display the fallback plain text `body` key `msgtype` then it SHOULD display the fallback plain text `body` key
@ -74,7 +74,7 @@ scheme matching one of: `https`, `http`, `ftp`, `mailto`, `magnet`)
`img` `img`
`width`, `height`, `alt`, `title`, `src` (provided it is a [Matrix `width`, `height`, `alt`, `title`, `src` (provided it is a [Matrix
Content (MXC) URI]()) Content (MXC) URI](#matrix-content-mxc-uris))
`ol` `ol`
`start` `start`
@ -128,15 +128,16 @@ can either be replaced with placeholder text (e.g. "\[REDACTED\]") or
the redacted message can be removed entirely from the messages view. the redacted message can be removed entirely from the messages view.
Events which have attachments (e.g. `m.image`, `m.file`) SHOULD be Events which have attachments (e.g. `m.image`, `m.file`) SHOULD be
uploaded using the [content repository module]() where available. The uploaded using the [content repository module](#content-repository)
resulting `mxc://` URI can then be used in the `url` key. where available. The resulting `mxc://` URI can then be used in the `url`
key.
Clients MAY include a client generated thumbnail image for an attachment Clients MAY include a client generated thumbnail image for an attachment
under a `info.thumbnail_url` key. The thumbnail SHOULD also be a under a `info.thumbnail_url` key. The thumbnail SHOULD also be a
`mxc://` URI. Clients displaying events with attachments can either use `mxc://` URI. Clients displaying events with attachments can either use
the client generated thumbnail or ask its homeserver to generate a the client generated thumbnail or ask its homeserver to generate a
thumbnail from the original attachment using the [content repository thumbnail from the original attachment using the [content repository
module](). module](#content-repository).
##### Recommendations when sending messages ##### Recommendations when sending messages
@ -259,15 +260,15 @@ number of possibilities for choosing a useful name. To ensure that rooms
are named consistently across clients, clients SHOULD use the following are named consistently across clients, clients SHOULD use the following
algorithm to choose a name: algorithm to choose a name:
1. If the room has an [m.room.name]() state event with a non-empty 1. If the room has an [m.room.name](#m.room.name) state event with a non-empty
`name` field, use the name given by that field. `name` field, use the name given by that field.
2. If the room has an [m.room.canonical\_alias]() state event with a 2. If the room has an [m.room.canonical\_alias](#m.room.canonical_alias) state event with a
valid `alias` field, use the alias given by that field as the name. valid `alias` field, use the alias given by that field as the name.
Note that clients should avoid using `alt_aliases` when calculating Note that clients should avoid using `alt_aliases` when calculating
the room name. the room name.
3. If none of the above conditions are met, a name should be composed 3. If none of the above conditions are met, a name should be composed
based on the members of the room. Clients should consider based on the members of the room. Clients should consider
[m.room.member]() events for users other than the logged-in user, as [m.room.member](#m.room.member) events for users other than the logged-in user, as
defined below. defined below.
1. If the number of `m.heroes` for the room are greater or equal to 1. If the number of `m.heroes` for the room are greater or equal to
`m.joined_member_count + m.invited_member_count - 1`, then use `m.joined_member_count + m.invited_member_count - 1`, then use
@ -382,7 +383,7 @@ The `formatted_body` should use the following template:
If the related event does not have a `formatted_body`, the event's If the related event does not have a `formatted_body`, the event's
`body` should be considered after encoding any HTML special characters. `body` should be considered after encoding any HTML special characters.
Note that the `href` in both of the anchors use a [matrix.to Note that the `href` in both of the anchors use a [matrix.to
URI](../appendices.html#matrix-to-navigation). URI](/appendices#matrixto-navigation).
######## Stripping the fallback ######## Stripping the fallback
@ -477,7 +478,7 @@ status code of 400.
#### Security considerations #### Security considerations
Messages sent using this module are not encrypted, although end to end Messages sent using this module are not encrypted, although end to end
encryption is in development (see [E2E module]()). encryption is in development (see [E2E module](#end-to-end-encryption)).
Clients should sanitise **all displayed keys** for unsafe HTML to Clients should sanitise **all displayed keys** for unsafe HTML to
prevent Cross-Site Scripting (XSS) attacks. This includes room names and prevent Cross-Site Scripting (XSS) attacks. This includes room names and

6
content/client-server-api/modules/mentions.md
View file

@ -7,11 +7,11 @@ weight: 300
This module allows users to mention other users, rooms, and groups This module allows users to mention other users, rooms, and groups
within a room message. This is achieved by including a [matrix.to within a room message. This is achieved by including a [matrix.to
URI](../appendices.html#matrix-to-navigation) in the HTML body of an URI](/appendices/#matrixto-navigation) in the HTML body of an
[m.room.message]() event. This module does not have any server-specific [m.room.message](#mroommessage) event. This module does not have any server-specific
behaviour to it. behaviour to it.
Mentions apply only to [m.room.message]() events where the `msgtype` is Mentions apply only to [m.room.message](#mroommessage) events where the `msgtype` is
`m.text`, `m.emote`, or `m.notice`. The `format` for the event must be `m.text`, `m.emote`, or `m.notice`. The `format` for the event must be
`org.matrix.custom.html` and therefore requires a `formatted_body`. `org.matrix.custom.html` and therefore requires a `formatted_body`.

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

@ -253,7 +253,7 @@ Parameters:
- `key`: A string that determines the power level the sender must have - `key`: A string that determines the power level the sender must have
to trigger notifications of a given type, such as `room`. Refer to to trigger notifications of a given type, such as `room`. Refer to
the [m.room.power\_levels]() event schema for information about what the [m.room.power\_levels](#mroompower_levels) event schema for information about what
the defaults are and how to interpret the event. The `key` is used the defaults are and how to interpret the event. The `key` is used
to look up the power level required to send a notification type from to look up the power level required to send a notification type from
the `notifications` object in the power level event content. the `notifications` object in the power level event content.

14
content/client-server-api/modules/room_previews.md
View file

@ -7,22 +7,22 @@ weight: 170
It is sometimes desirable to offer a preview of a room, where a user can It is sometimes desirable to offer a preview of a room, where a user can
"lurk" and read messages posted to the room, without joining the room. "lurk" and read messages posted to the room, without joining the room.
This can be particularly effective when combined with [Guest Access](). This can be particularly effective when combined with [Guest Access](#guest-access).
Previews are implemented via the `world_readable` [Room History Previews are implemented via the `world_readable` [Room History
Visibility](). setting, along with a special version of the [GET Visibility](#room-history-visibility). setting, along with a special version of the [GET
/events](#get-matrix-client-%CLIENT_MAJOR_VERSION%-events) endpoint. /events](#get_matrixclientr0events) endpoint.
#### Client behaviour #### Client behaviour
A client wishing to view a room without joining it should call [GET A client wishing to view a room without joining it should call [GET
/rooms/:room\_id/initialSync](#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-initialsync), /rooms/:room\_id/initialSync](#get_matrixclientr0roomsroomidinitialsync),
followed by [GET /events](#peeking_events_api). Clients will need to do followed by [GET /events](#get_matrixclientr0events). Clients will need to do
this in parallel for each room they wish to view. this in parallel for each room they wish to view.
Clients can of course also call other endpoints such as [GET Clients can of course also call other endpoints such as [GET
/rooms/:room\_id/messages](#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-messages) /rooms/:room\_id/messages](#get_matrixclientr0roomsroomidmessages)
and [GET /search](#get-matrix-client-%CLIENT_MAJOR_VERSION%-search) to and [GET /search](#post_matrixclientr0search) to
access events outside the `/events` stream. access events outside the `/events` stream.
{{peeking\_events\_cs\_http\_api}} {{peeking\_events\_cs\_http\_api}}

4
content/client-server-api/modules/secrets.md
View file

@ -20,7 +20,7 @@ as a string.
#### Storage #### Storage
When secrets are stored on the server, they are stored in the user's When secrets are stored on the server, they are stored in the user's
[account-data](#module-account-data), using an event type equal to the [account-data](#client-config), using an event type equal to the
secret's identifier. The keys that secrets are encrypted with are secret's identifier. The keys that secrets are encrypted with are
described by data that is also stored in the user's account-data. Users described by data that is also stored in the user's account-data. Users
can have multiple keys, allowing them to control what sets of secrets can have multiple keys, allowing them to control what sets of secrets
@ -103,7 +103,7 @@ of the data.
<tr class="odd"> <tr class="odd">
<td><p>encrypted</p></td> <td><p>encrypted</p></td>
<td><p>{string: object}</p></td> <td><p>{string: object}</p></td>
<td><p><strong>Required.</strong> Map from key ID the encrypted data. The exact format for the encrypted data is dependent on the key algorithm. See the definition of <code>AesHmacSha2EncryptedData</code> in the <a href="#m.secret_storage.v1.aes-hmac-sha2">m.secret_storage.v1.aes-hmac-sha2</a> section.</p></td> <td><p><strong>Required.</strong> Map from key ID the encrypted data. The exact format for the encrypted data is dependent on the key algorithm. See the definition of <code>AesHmacSha2EncryptedData</code> in the <a href="#msecret_storagev1aes-hmac-sha2">m.secret_storage.v1.aes-hmac-sha2</a> section.</p></td>
</tr> </tr>
</tbody> </tbody>
</table> </table>

4
content/client-server-api/modules/send_to_device.md
View file

@ -3,7 +3,7 @@ type: module
weight: 80 weight: 80
--- ---
### Send-to-Device messaging<span id="module:to_device"></span> ### Send-to-Device messaging
This module provides a means by which clients can exchange signalling This module provides a means by which clients can exchange signalling
messages without them being stored permanently as part of a shared messages without them being stored permanently as part of a shared
@ -48,7 +48,7 @@ recommended as a reasonable limit.
If the client sends messages to users on remote domains, those messages If the client sends messages to users on remote domains, those messages
should be sent on to the remote servers via should be sent on to the remote servers via
[federation](../server_server/%SERVER_RELEASE_LABEL%.html#send-to-device-messaging). [federation](/server-server-api#send-to-device-messaging).
#### Protocol definitions #### Protocol definitions

6
content/client-server-api/modules/server_acls.md
View file

@ -7,14 +7,14 @@ weight: 290
In some scenarios room operators may wish to prevent a malicious or In some scenarios room operators may wish to prevent a malicious or
untrusted server from participating in their room. Sending an untrusted server from participating in their room. Sending an
[m.room.server\_acl]() state event into a room is an effective way to [m.room.server\_acl](#mroomserver_acl) state event into a room is an effective way to
prevent the server from participating in the room at the federation prevent the server from participating in the room at the federation
level. level.
Server ACLs can also be used to make rooms only federate with a limited Server ACLs can also be used to make rooms only federate with a limited
set of servers, or retroactively make the room no longer federate with set of servers, or retroactively make the room no longer federate with
any other server, similar to setting the `m.federate` value on the any other server, similar to setting the `m.federate` value on the
[m.room.create]() event. [m.room.create](#mroomcreate) event.
{{m\_room\_server\_acl\_event}} {{m\_room\_server\_acl\_event}}
@ -46,7 +46,7 @@ excluded from the room.
#### Server behaviour #### Server behaviour
Servers MUST prevent blacklisted servers from sending events or Servers MUST prevent blacklisted servers from sending events or
participating in the room when an [m.room.server\_acl]() event is participating in the room when an [m.room.server\_acl](#mroomserver_acl) event is
present in the room state. Which APIs are specifically affected are present in the room state. Which APIs are specifically affected are
described in the Server-Server API specification. described in the Server-Server API specification.

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

@ -42,7 +42,7 @@ encouraged to treat syncing users as "active".
Clients can identify the server notices room by the `m.server_notice` Clients can identify the server notices room by the `m.server_notice`
tag on the room. Active notices are represented by the [pinned tag on the room. Active notices are represented by the [pinned
events](#m-room-pinned-events) in the server notices room. Server notice events](#mroompinned_events) in the server notices room. Server notice
events pinned in that room should be shown to the user through special events pinned in that room should be shown to the user through special
UI and not through the normal pinned events interface in the client. For UI and not through the normal pinned events interface in the client. For
example, clients may show warning banners or bring up dialogs to get the example, clients may show warning banners or bring up dialogs to get the

14
content/client-server-api/modules/sso_login.md
View file

@ -28,7 +28,7 @@ used to communicate with the authentication server. Different Matrix
homeserver implementations might support different SSO protocols. homeserver implementations might support different SSO protocols.
Clients and homeservers implementing the SSO flow will need to consider Clients and homeservers implementing the SSO flow will need to consider
both [login]() and [user-interactive authentication](). The flow is both [login](#login) and [user-interactive authentication](#user-interactive-authentication-api). The flow is
similar in both cases, but there are slight differences. similar in both cases, but there are slight differences.
Typically, SSO systems require a single "callback" URI to be configured Typically, SSO systems require a single "callback" URI to be configured
@ -170,9 +170,9 @@ The homeserver then proceeds as follows:
1. The homeserver MUST map the user details received from the 1. The homeserver MUST map the user details received from the
authentication server to a valid [Matrix user authentication server to a valid [Matrix user
identifier](../appendices.html#user-identifiers). The guidance in identifier](/appendices#user-identifiers). The guidance in
[Mapping from other character [Mapping from other character
sets](../appendices.html#mapping-from-other-character-sets) may be sets](/appendices#mapping-from-other-character-sets) may be
useful. useful.
2. If the generated user identifier represents a new user, it should be 2. If the generated user identifier represents a new user, it should be
registered as a new user. registered as a new user.
@ -212,7 +212,7 @@ The homeserver then proceeds as follows:
It may be appropriate to whitelist a set of known-trusted client It may be appropriate to whitelist a set of known-trusted client
URLs in this process. In particular, the homeserver's own [login URLs in this process. In particular, the homeserver's own [login
fallback]() implementation could be excluded. fallback](#login-fallback) implementation could be excluded.
2. For added security, homeservers SHOULD guard against unsolicited 2. For added security, homeservers SHOULD guard against unsolicited
authentication attempts by tracking pending requests. One way to do authentication attempts by tracking pending requests. One way to do
@ -223,14 +223,14 @@ The homeserver then proceeds as follows:
#### SSO during User-Interactive Authentication #### SSO during User-Interactive Authentication
[User-interactive authentication]() is used by client-server endpoints [User-interactive authentication](#user-interactive-authentication-api) is used by client-server endpoints
which require additional confirmation of the user's identity (beyond which require additional confirmation of the user's identity (beyond
holding an access token). Typically this means that the user must holding an access token). Typically this means that the user must
re-enter their password, but for homeservers which delegate to an SSO re-enter their password, but for homeservers which delegate to an SSO
server, this means redirecting to the authentication server during server, this means redirecting to the authentication server during
user-interactive auth. user-interactive auth.
The implemementation of this is based on the [Fallback]() mechanism for The implemementation of this is based on the [Fallback](#fallback) mechanism for
user-interactive auth. user-interactive auth.
#### Client behaviour #### Client behaviour
@ -274,7 +274,7 @@ may require additional calls to the authentication server, and/or may
require checking a signature on the response. require checking a signature on the response.
The homeserver then returns the [user-interactive authentication The homeserver then returns the [user-interactive authentication
fallback completion]() page to the user's browser. fallback completion](#fallback) page to the user's browser.
###### Security considerations ###### Security considerations

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

@ -10,7 +10,7 @@ messaging sessions.
Sticker messages are specialised image messages that are displayed Sticker messages are specialised image messages that are displayed
without controls (e.g. no "download" link, or light-box view on click, without controls (e.g. no "download" link, or light-box view on click,
as would be displayed for for [m.image]() events). as would be displayed for for [m.image](#mimage) events).
Sticker messages are intended to provide simple "reaction" events in the Sticker messages are intended to provide simple "reaction" events in the
message timeline. The matrix client should provide some mechanism to message timeline. The matrix client should provide some mechanism to

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

@ -57,7 +57,7 @@ tags are defined in the `m.*` namespace:
- `m.lowpriority`: These should be shown with lower precedence than - `m.lowpriority`: These should be shown with lower precedence than
others. others.
- `m.server_notice`: Used to identify [Server Notice - `m.server_notice`: Used to identify [Server Notice
Rooms](#module-server-notices). Rooms](#server-notices).
{{m\_tag\_event}} {{m\_tag\_event}}

4
content/client-server-api/modules/third_party_invites.md
View file

@ -27,7 +27,7 @@ it should insert an `m.room.member` event into the room's graph for that
user, with `content.membership` = `invite`, as well as a user, with `content.membership` = `invite`, as well as a
`content.third_party_invite` property which contains proof that the `content.third_party_invite` property which contains proof that the
invitee does indeed own that third party identifier. See the invitee does indeed own that third party identifier. See the
[m.room.member](#m-room-member) schema for more information. [m.room.member](#mroommember) schema for more information.
#### Events #### Events
@ -198,7 +198,7 @@ at any time - the completion is not shown in the diagram.
H1 MUST verify the request from H3 to ensure the `signed` property is H1 MUST verify the request from H3 to ensure the `signed` property is
correct as well as the `key_validity_url` as still being valid. This is correct as well as the `key_validity_url` as still being valid. This is
done by making a request to the [identity server done by making a request to the [identity server
/isvalid](../identity_service/%IDENTITY_RELEASE_LABEL%.html#get-matrix-identity-v2-pubkey-isvalid) /isvalid](/identity-service-api/#get_matrixidentityv2pubkeyisvalid)
endpoint, using the provided URL rather than constructing a new one. The endpoint, using the provided URL rather than constructing a new one. The
query string and response for the provided URL must match the Identity query string and response for the provided URL must match the Identity
Service Specification. Service Specification.

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

@ -8,7 +8,7 @@ weight: 20
This module outlines how two users in a room can set up a Voice over IP This module outlines how two users in a room can set up a Voice over IP
(VoIP) call to each other. Voice and video calls are built upon the (VoIP) call to each other. Voice and video calls are built upon the
WebRTC 1.0 standard. Call signalling is achieved by sending [message WebRTC 1.0 standard. Call signalling is achieved by sending [message
events]() to the room. In this version of the spec, only two-party events](#events) to the room. In this version of the spec, only two-party
communication is supported (e.g. between two peers, or between a peer communication is supported (e.g. between two peers, or between a peer
and a multi-point conferencing unit). This means that clients MUST only and a multi-point conferencing unit). This means that clients MUST only
send call events to rooms with exactly two participants. send call events to rooms with exactly two participants.

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

@ -56,7 +56,7 @@ not necessarily provide evidence that they have validated associations,
but claim to have done so. Establishing the trustworthiness of an but claim to have done so. Establishing the trustworthiness of an
individual identity server is left as an exercise for the client. individual identity server is left as an exercise for the client.
3PID types are described in [3PID Types](../appendices.html#pid-types) 3PID types are described in [3PID Types](/appendices#pid-types)
Appendix. Appendix.
## API standards ## API standards
@ -236,7 +236,7 @@ has just accepted are appended to `m.accepted_terms`.
An identity server has some long-term public-private keypairs. These are An identity server has some long-term public-private keypairs. These are
named in a scheme `algorithm:identifier`, e.g. `ed25519:0`. When signing named in a scheme `algorithm:identifier`, e.g. `ed25519:0`. When signing
an association, the standard [Signing an association, the standard [Signing
JSON](../appendices.html#signing-json) algorithm applies. JSON](/appendices#signing-json) algorithm applies.
The identity server may also keep track of some short-term The identity server may also keep track of some short-term
public-private keypairs, which may have different usage and lifetime public-private keypairs, which may have different usage and lifetime
@ -308,8 +308,8 @@ internal state of the hash function.
After formatting each query, the string is run through SHA-256 as After formatting each query, the string is run through SHA-256 as
defined by [RFC 4634](https://tools.ietf.org/html/rfc4634). The defined by [RFC 4634](https://tools.ietf.org/html/rfc4634). The
resulting bytes are then encoded using URL-Safe [Unpadded resulting bytes are then encoded using URL-Safe [Unpadded
Base64](../appendices.html#unpadded-base64) (similar to [room version Base64](/appendices#unpadded-base64) (similar to [room version
4's event ID format](../rooms/v4.html#event-ids)). 4's event ID format](/rooms/v4#event-ids)).
An example set of queries when using the pepper `matrixrocks` would be: An example set of queries when using the pepper `matrixrocks` would be:
@ -448,7 +448,7 @@ is associated with a Matrix user ID.
At a later point, if the owner of that particular 3PID binds it with a At a later point, if the owner of that particular 3PID binds it with a
Matrix user ID, the identity server will attempt to make an HTTP POST to Matrix user ID, the identity server will attempt to make an HTTP POST to
the Matrix user's homeserver via the the Matrix user's homeserver via the
[/3pid/onbind](../server_server/%SERVER_RELEASE_LABEL%.html#put-matrix-federation-v1-3pid-onbind) [/3pid/onbind](/server-server-api#put_matrixfederationv13pidonbind)
endpoint. The request MUST be signed with a long-term private key for endpoint. The request MUST be signed with a long-term private key for
the identity server. the identity server.

2
content/push-gateway-api.md
View file

@ -74,6 +74,6 @@ the homeserver is performing a push where the `format` is
Note that most of the values and behaviour of this endpoint is described Note that most of the values and behaviour of this endpoint is described
by the Client-Server API's [Push by the Client-Server API's [Push
Module](../client_server/%CLIENT_RELEASE_LABEL%.html#module-push). Module](/client-server-api#push-notifications).
{{push\_notifier\_push\_http\_api}} {{push\_notifier\_push\_http\_api}}

4
content/rooms/v1.md
View file

@ -155,7 +155,7 @@ The rules are as follows:
1. have duplicate entries for a given `type` and `state_key` pair 1. have duplicate entries for a given `type` and `state_key` pair
2. have entries whose `type` and `state_key` don't match those 2. have entries whose `type` and `state_key` don't match those
specified by the [auth events specified by the [auth events
selection](../server_server/%SERVER_RELEASE_LABEL%.html#auth-events-selection) selection](/server-server-api#auth-events-selection)
algorithm described in the server specification. algorithm described in the server specification.
3. If event does not have a `m.room.create` in its `auth_events`, 3. If event does not have a `m.room.create` in its `auth_events`,
reject. reject.
@ -281,5 +281,5 @@ Events in version 1 rooms have the following structure:
### Canonical JSON ### Canonical JSON
Servers MUST NOT strictly enforce the JSON format specified in the Servers MUST NOT strictly enforce the JSON format specified in the
[appendices](../appendices.html#canonical-json) for the reasons [appendices](/appendices#canonical-json) for the reasons
described there. described there.

6
content/rooms/v2.md
View file

@ -4,7 +4,7 @@ type: docs
weight: 20 weight: 20
--- ---
This room version builds off of [version 1](v1.html) with an improved This room version builds off of [version 1](/rooms/v1) with an improved
state resolution algorithm. state resolution algorithm.
## Server implementation components ## Server implementation components
@ -16,7 +16,7 @@ unaffected by the details contained here, and can safely ignore their
presence. presence.
{{% /boxes/warning %}} {{% /boxes/warning %}}
Room version 2 uses the base components of [room version 1](v1.html), Room version 2 uses the base components of [room version 1](/rooms/v1),
changing only the state resolution algorithm. changing only the state resolution algorithm.
### State resolution ### State resolution
@ -120,7 +120,7 @@ The *iterative auth checks algorithm* takes as input an initial room
state and a sorted list of state events, and constructs a new room state state and a sorted list of state events, and constructs a new room state
by iterating through the event list and applying the state event to the by iterating through the event list and applying the state event to the
room state if the state event is allowed by the [authorization room state if the state event is allowed by the [authorization
rules](../server_server/%SERVER_RELEASE_LABEL%.html#authorization-rules). rules](/server-server-api#authorization-rules).
If the state event is not allowed by the authorization rules, then the If the state event is not allowed by the authorization rules, then the
event is ignored. If a `(event_type, state_key)` key that is required event is ignored. If a `(event_type, state_key)` key that is required
for checking the authorization rules is not present in the state, then for checking the authorization rules is not present in the state, then

10
content/rooms/v3.md
View file

@ -4,7 +4,7 @@ type: docs
weight: 30 weight: 30
--- ---
This room version builds on [version 2](v2.html) with an improved event This room version builds on [version 2](/rooms/v2) with an improved event
format. format.
## Client considerations ## Client considerations
@ -31,7 +31,7 @@ use cases should reference.
{{% /boxes/warning %}} {{% /boxes/warning %}}
Room version 3 uses the state resolution algorithm defined in [room Room version 3 uses the state resolution algorithm defined in [room
version 2](v2.html), and the event format defined here. version 2](/rooms/v2), and the event format defined here.
### Event IDs ### Event IDs
@ -46,9 +46,9 @@ hashes on an event to determine its ID.
{{% /boxes/rationale %}} {{% /boxes/rationale %}}
The event ID is the [reference The event ID is the [reference
hash](../server_server/%SERVER_RELEASE_LABEL%.html#reference-hashes) of hash](/server-server-api#calculating-the-reference-hash-for-an-event) of
the event encoded using [Unpadded the event encoded using [Unpadded
Base64](../appendices.html#unpadded-base64), prefixed with `$`. A Base64](/appendices#unpadded-base64), prefixed with `$`. A
resulting event ID using this approach should look similar to resulting event ID using this approach should look similar to
`$CD66HAED5npg6074c6pDtLKalHjVfYb2q4Q3LZgrW6o`. `$CD66HAED5npg6074c6pDtLKalHjVfYb2q4Q3LZgrW6o`.
@ -97,4 +97,4 @@ version due to the change in event format:
power levels. power levels.
The remaining rules are the same as [room version The remaining rules are the same as [room version
1](v1.html#authorization-rules). 1](/rooms/v1#authorization-rules).

8
content/rooms/v4.md
View file

@ -4,7 +4,7 @@ type: docs
weight: 40 weight: 40
--- ---
This room version builds on [version 3](v3.html) using a different This room version builds on [version 3](/rooms/v3) using a different
encoding for event IDs. encoding for event IDs.
## Client considerations ## Client considerations
@ -30,7 +30,7 @@ use cases should reference.
{{% /boxes/warning %}} {{% /boxes/warning %}}
Room version 4 uses the same algorithms defined in [room version Room version 4 uses the same algorithms defined in [room version
3](v3.html), however using URL-safe base64 to generate the event ID. 3](/rooms/v3), however using URL-safe base64 to generate the event ID.
### Event IDs ### Event IDs
@ -43,9 +43,9 @@ generally made administration harder.
{{% /boxes/rationale %}} {{% /boxes/rationale %}}
The event ID is the [reference The event ID is the [reference
hash](../server_server/%SERVER_RELEASE_LABEL%.html#reference-hashes) of hash](/server-server-api#calculating-the-reference-hash-for-an-event) of
the event encoded using a variation of [Unpadded the event encoded using a variation of [Unpadded
Base64](../appendices.html#unpadded-base64) which replaces the 62nd and Base64](/appendices#unpadded-base64) which replaces the 62nd and
63rd characters with `-` and `_` instead of using `+` and `/`. This 63rd characters with `-` and `_` instead of using `+` and `/`. This
matches [RFC4648's definition of URL-safe matches [RFC4648's definition of URL-safe
base64](https://tools.ietf.org/html/rfc4648#section-5). Event IDs are base64](https://tools.ietf.org/html/rfc4648#section-5). Event IDs are

10
content/rooms/v5.md
View file

@ -4,14 +4,14 @@ type: docs
weight: 50 weight: 50
--- ---
This room version builds on [version 4](v4.html) while enforcing signing This room version builds on [version 4](/rooms/v4) while enforcing signing
key validity periods for events. key validity periods for events.
## Client considerations ## Client considerations
There are no specific requirements for clients in this room version. There are no specific requirements for clients in this room version.
Clients should be aware of event ID changes in [room version Clients should be aware of event ID changes in [room version
4](v4.html), however. 4](/rooms/v4), however.
## Server implementation components ## Server implementation components
@ -24,7 +24,7 @@ use cases should reference.
{{% /boxes/warning %}} {{% /boxes/warning %}}
Room version 5 uses the same algorithms defined in [room version Room version 5 uses the same algorithms defined in [room version
4](v4.html), ensuring that signing key validity is respected. 4](/rooms/v4), ensuring that signing key validity is respected.
### Signing key validity period ### Signing key validity period
@ -32,9 +32,9 @@ When validating event signatures, servers MUST enforce the
`valid_until_ts` property from a key request is at least as large as the `valid_until_ts` property from a key request is at least as large as the
`origin_server_ts` for the event being validated. Servers missing a copy `origin_server_ts` for the event being validated. Servers missing a copy
of the signing key MUST try to obtain one via the [GET of the signing key MUST try to obtain one via the [GET
/\_matrix/key/v2/server](../server_server/%SERVER_RELEASE_LABEL%.html#get-matrix-key-v2-server-keyid) /\_matrix/key/v2/server](/server-server-api#get_matrixkeyv2serverkeyid)
or [POST or [POST
/\_matrix/key/v2/query](../server_server/%SERVER_RELEASE_LABEL%.html#post-matrix-key-v2-query) /\_matrix/key/v2/query](/server-server-api#post_matrixkeyv2query)
APIs. When using the `/query` endpoint, servers MUST set the APIs. When using the `/query` endpoint, servers MUST set the
`minimum_valid_until_ts` property to prompt the notary server to attempt `minimum_valid_until_ts` property to prompt the notary server to attempt
to refresh the key if appropriate. to refresh the key if appropriate.

10
content/rooms/v6.md
View file

@ -4,12 +4,12 @@ type: docs
weight: 60 weight: 60
--- ---
This room version builds on [version 5](v5.html) while changing various This room version builds on [version 5](/rooms/v5) while changing various
authorization rules performed on events. authorization rules performed on events.
## Client considerations ## Client considerations
The redaction algorithm has changed from [room version 1](v1.html) to The redaction algorithm has changed from [room version 1](/rooms/v1) to
remove all rules against events of type `m.room.aliases`. Room versions remove all rules against events of type `m.room.aliases`. Room versions
2, 3, 4, and 5 all use v1's redaction algorithm. The algorithm is 2, 3, 4, and 5 all use v1's redaction algorithm. The algorithm is
otherwise unchanged. otherwise unchanged.
@ -25,7 +25,7 @@ use cases should reference.
{{% /boxes/warning %}} {{% /boxes/warning %}}
Room version 6 makes the following alterations to algorithms described Room version 6 makes the following alterations to algorithms described
in [room version 5](v5.html). in [room version 5](/rooms/v5).
### Redactions ### Redactions
@ -71,13 +71,13 @@ follows:
... ...
The remaining rules are the same as in [room version The remaining rules are the same as in [room version
3](v3.html#authorization-rules-for-events) (the last inherited room 3](/rooms/v3#authorization-rules-for-events) (the last inherited room
version to specify the authorization rules). version to specify the authorization rules).
### Canonical JSON ### Canonical JSON
Servers MUST strictly enforce the JSON format specified in the Servers MUST strictly enforce the JSON format specified in the
[appendices](../appendices.html#canonical-json). This translates to a [appendices](/appendices#canonical-json). This translates to a
400 `M_BAD_JSON` error on most endpoints, or discarding of events over 400 `M_BAD_JSON` error on most endpoints, or discarding of events over
federation. For example, the Federation API's `/send` endpoint would federation. For example, the Federation API's `/send` endpoint would
discard the event whereas the Client Server API's `/send/{eventType}` discard the event whereas the Client Server API's `/send/{eventType}`

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

@ -87,7 +87,7 @@ addition, all strings MUST be encoded as UTF-8.
Each Matrix homeserver is identified by a server name consisting of a Each Matrix homeserver is identified by a server name consisting of a
hostname and an optional port, as described by the hostname and an optional port, as described by the
[grammar](../appendices.html#server-name). Where applicable, a delegated [grammar](/appendices#server-name). Where applicable, a delegated
server name uses the same grammar. server name uses the same grammar.
Server names are resolved to an IP address and port to connect to, and Server names are resolved to an IP address and port to connect to, and
@ -625,7 +625,7 @@ the room. What should the name of the room be at E5?
The algorithm to be used for state resolution depends on the room The algorithm to be used for state resolution depends on the room
version. For a description of each room version's algorithm, please see version. For a description of each room version's algorithm, please see
the [room version specification](../index.html#room-versions). the [room version specification](/#room-versions).
## Backfilling and retrieving missing events ## Backfilling and retrieving missing events
@ -785,7 +785,7 @@ the event to other servers in the room.
{{% boxes/note %}} {{% boxes/note %}}
More information about third party invites is available in the More information about third party invites is available in the
[Client-Server API](../client_server/%CLIENT_RELEASE_LABEL%.html) under [Client-Server API](/client-server-api) under
the Third Party Invites module. the Third Party Invites module.
{{% /boxes/note %}} {{% /boxes/note %}}
@ -795,7 +795,7 @@ an e-mail or a phone number).
This identifier and its bindings to Matrix IDs are verified by an This identifier and its bindings to Matrix IDs are verified by an
identity server implementing the [Identity Service identity server implementing the [Identity Service
API](../identity_service/%IDENTITY_RELEASE_LABEL%.html). API](/identity-service-api).
### Cases where an association exists for a third-party identifier ### Cases where an association exists for a third-party identifier
@ -816,7 +816,7 @@ provided as a response to the invite storage request.
When a third-party identifier with pending invites gets bound to a When a third-party identifier with pending invites gets bound to a
Matrix ID, the identity server will send a POST request to the ID's Matrix ID, the identity server will send a POST request to the ID's
homeserver as described in the [Invitation homeserver as described in the [Invitation
Storage](../identity_service/%IDENTITY_RELEASE_LABEL%.html#invitation-storage) Storage](/identity-service-api#invitation-storage)
section of the Identity Service API. section of the Identity Service API.
The following process applies for each invite sent by the identity The following process applies for each invite sent by the identity
@ -862,7 +862,7 @@ from the user owning the invited third-party identifier.
## Public Room Directory ## Public Room Directory
To complement the [Client-Server To complement the [Client-Server
API](../client_server/%CLIENT_RELEASE_LABEL%.html)'s room directory, API](/client-server-api)'s room directory,
homeservers need a way to query the public rooms for another server. homeservers need a way to query the public rooms for another server.
This can be done by making a request to the `/publicRooms` endpoint for This can be done by making a request to the `/publicRooms` endpoint for
the server the room directory should be retrieved for. the server the room directory should be retrieved for.
@ -932,7 +932,7 @@ and kept up-to-date. This is critical for reliable end-to-end
encryption, in order for users to know which devices are participating encryption, in order for users to know which devices are participating
in a room. It's also required for to-device messaging to work. This in a room. It's also required for to-device messaging to work. This
section is intended to complement the [Device Management section is intended to complement the [Device Management
module](../client_server/%CLIENT_RELEASE_LABEL%.html#device-management) module](/client-server-api#device-management)
of the Client-Server API. of the Client-Server API.
Matrix currently uses a custom pubsub system for synchronising Matrix currently uses a custom pubsub system for synchronising
@ -976,7 +976,7 @@ recognise, it must resynchronise its list by calling the
## End-to-End Encryption ## End-to-End Encryption
This section complements the [End-to-End Encryption This section complements the [End-to-End Encryption
module](../client_server/%CLIENT_RELEASE_LABEL%.html#end-to-end-encryption) module](/client-server-api#end-to-end-encryption)
of the Client-Server API. For detailed information about end-to-end of the Client-Server API. For detailed information about end-to-end
encryption, please see that module. encryption, please see that module.
@ -1003,20 +1003,20 @@ using the following EDU:
Attachments to events (images, files, etc) are uploaded to a homeserver Attachments to events (images, files, etc) are uploaded to a homeserver
via the Content Repository described in the [Client-Server via the Content Repository described in the [Client-Server
API](../client_server/%CLIENT_RELEASE_LABEL%.html). When a server wishes API](/client-server-api). When a server wishes
to serve content originating from a remote server, it needs to ask the to serve content originating from a remote server, it needs to ask the
remote server for the media. remote server for the media.
Servers should use the server described in the Matrix Content URI, which Servers should use the server described in the Matrix Content URI, which
has the format `mxc://{ServerName}/{MediaID}`. Servers should use the has the format `mxc://{ServerName}/{MediaID}`. Servers should use the
download endpoint described in the [Client-Server download endpoint described in the [Client-Server
API](../client_server/%CLIENT_RELEASE_LABEL%.html), being sure to use API](/client-server-api), being sure to use
the `allow_remote` parameter (set to `false`). the `allow_remote` parameter (set to `false`).
## Server Access Control Lists (ACLs) ## Server Access Control Lists (ACLs)
Server ACLs and their purpose are described in the [Server Server ACLs and their purpose are described in the [Server
ACLs](../client_server/%CLIENT_RELEASE_LABEL%.html#module-server-acls) ACLs](/client-server-api#server-access-control-lists-acls-for-rooms)
section of the Client-Server API. section of the Client-Server API.
When a remote server makes a request, it MUST be verified to be allowed When a remote server makes a request, it MUST be verified to be allowed
@ -1050,13 +1050,13 @@ redact non-essential parts of an event.
Before signing the event, the *content hash* of the event is calculated Before signing the event, the *content hash* of the event is calculated
as described below. The hash is encoded using [Unpadded as described below. The hash is encoded using [Unpadded
Base64](../appendices.html#unpadded-base64) and stored in the event Base64](/appendices#unpadded-base64) and stored in the event
object, in a `hashes` object, under a `sha256` key. object, in a `hashes` object, under a `sha256` key.
The event object is then *redacted*, following the [redaction The event object is then *redacted*, following the [redaction
algorithm](../client_server/%CLIENT_RELEASE_LABEL%.html#redactions). algorithm](/client-server-api#redactions).
Finally it is signed as described in [Signing Finally it is signed as described in [Signing
JSON](../appendices.html#signing-json), using the server's signing key JSON](/appendices#signing-json), using the server's signing key
(see also [Retrieving server keys](#retrieving-server-keys)). (see also [Retrieving server keys](#retrieving-server-keys)).
The signature is then copied back to the original event object. The signature is then copied back to the original event object.
@ -1071,10 +1071,10 @@ receiving server should check the hashes and signatures on that event.
First the signature is checked. The event is redacted following the First the signature is checked. The event is redacted following the
[redaction [redaction
algorithm](../client_server/%CLIENT_RELEASE_LABEL%.html#redactions), and algorithm](/client-server-api#redactions), and
the resultant object is checked for a signature from the originating the resultant object is checked for a signature from the originating
server, following the algorithm described in [Checking for a server, following the algorithm described in [Checking for a
signature](../appendices.html#checking-for-a-signature). Note that this signature](/appendices#checking-for-a-signature). Note that this
step should succeed whether we have been sent the full event or a step should succeed whether we have been sent the full event or a
redacted copy. redacted copy.
@ -1103,14 +1103,14 @@ the full copy it received.
The *reference hash* of an event covers the essential fields of an The *reference hash* of an event covers the essential fields of an
event, including content hashes. It is used for event identifiers in event, including content hashes. It is used for event identifiers in
some room versions. See the [room version some room versions. See the [room version
specification](../index.html#room-versions) for more information. It is specification](/#room-versions) for more information. It is
calculated as follows. calculated as follows.
1. The event is put through the redaction algorithm. 1. The event is put through the redaction algorithm.
2. The `signatures`, `age_ts`, and `unsigned` properties are removed 2. The `signatures`, `age_ts`, and `unsigned` properties are removed
from the event, if present. from the event, if present.
3. The event is converted into [Canonical 3. The event is converted into [Canonical
JSON](../appendices.html#canonical-json). JSON](/appendices#canonical-json).
4. A sha256 hash is calculated on the resulting JSON object. 4. A sha256 hash is calculated on the resulting JSON object.
### Calculating the content hash for an event ### Calculating the content hash for an event
@ -1120,7 +1120,7 @@ The *content hash* of an event covers the complete event including the
First, any existing `unsigned`, `signature`, and `hashes` members are First, any existing `unsigned`, `signature`, and `hashes` members are
removed. The resulting object is then encoded as [Canonical removed. The resulting object is then encoded as [Canonical
JSON](../appendices.html#canonical-json), and the JSON is hashed using JSON](/appendices#canonical-json), and the JSON is hashed using
SHA-256. SHA-256.
### Example code ### Example code