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

Support alerts (notes, warnings, rationales)

Browse source
This commit is contained in:
Will 2021-01-20 12:34:49 -08:00
parent ab64bda76d
commit 338434bfcd
No known key found for this signature in database
GPG key ID: 385872BB265E8BF8
22 changed files with 194 additions and 138 deletions
Download patch file Download diff file Expand all files Collapse all files

33
assets-hugo/scss/custom.scss
View file

@ -209,6 +209,39 @@ footer {
} }
/* Styles for alert boxes */
.alert {
&.note {
&:not(.omit-title):before {
content: "INFO: ";
font-weight: $font-weight-bold;
}
border: 2px solid $note;
border-left-width: 5px;
background: $note-background;
}
&.rationale {
&:not(.omit-title):before {
content: "RATIONALE: ";
font-weight: $font-weight-bold;
}
border: 2px solid $note;
border-left-width: 5px;
background: $note-background;
}
&.warning {
&:not(.omit-title):before {
content: "WARNING: ";
font-weight: $font-weight-bold;
}
border: 2px solid $warning;
border-left-width: 5px;
background: $warning-background;
}
}
/* Miscellaneous custom bits */ /* Miscellaneous custom bits */
/* Update link colours for MAtrix style */ /* Update link colours for MAtrix style */

8
content/_index.md
View file

@ -35,13 +35,13 @@ browsing the Client-Server API.
### Matrix versions ### Matrix versions
Note {{% boxes/note %}}
As of June 10th 2019, the Matrix specification is considered out of beta As of June 10th 2019, the Matrix specification is considered out of beta
-indicating that all currently released APIs are considered stable and -indicating that all currently released APIs are considered stable and
secure to the best of our knowledge, and the spec should contain the secure to the best of our knowledge, and the spec should contain the
complete information necessary to develop production-grade complete information necessary to develop production-grade
implementations of Matrix without the need for external reference. implementations of Matrix without the need for external reference.
{{% /boxes/note %}}
Matrix 1.0 (released June 10th, 2019) consists of the following minimum Matrix 1.0 (released June 10th, 2019) consists of the following minimum
API versions: API versions:
@ -335,13 +335,13 @@ participating servers in a room, currently using full mesh topology.
Servers may also request backfill of events over federation from the Servers may also request backfill of events over federation from the
other servers participating in a room. other servers participating in a room.
Note {{% boxes/note %}}
Events are not limited to the types defined in this specification. New Events are not limited to the types defined in this specification. New
or custom event types can be created on a whim using the Java package or custom event types can be created on a whim using the Java package
naming convention. For example, a `com.example.game.score` event can be naming convention. For example, a `com.example.game.score` event can be
sent by clients and other clients would receive it through Matrix, sent by clients and other clients would receive it through Matrix,
assuming the client has access to the `com.example` namespace. assuming the client has access to the `com.example` namespace.
{{% /boxes/note %}}
#### Room Aliases #### Room Aliases

32
content/appendices.md
View file

@ -74,18 +74,18 @@ to be in the range where they can be accurately represented using IEEE
double precision floating point numbers since a number of JSON libraries double precision floating point numbers since a number of JSON libraries
represent all numbers using this representation. represent all numbers using this representation.
Warning {{% boxes/warning %}}
Events in room versions 1, 2, 3, 4, and 5 might not be fully compliant Events in room versions 1, 2, 3, 4, and 5 might not be fully compliant
with these restrictions. Servers SHOULD be capable of handling JSON with these restrictions. Servers SHOULD be capable of handling JSON
which is considered invalid by these restrictions where possible. which is considered invalid by these restrictions where possible.
The most notable consideration is that integers might not be in the The most notable consideration is that integers might not be in the
range specified above. range specified above.
{{% /boxes/warning %}}
Note {{% boxes/note %}}
Float values are not permitted by this encoding. Float values are not permitted by this encoding.
{{% /boxes/note %}}
```py ```py
import json import json
@ -415,12 +415,12 @@ Examples of valid server names are:
- `[1234:5678::abcd]` (IPv6 literal) - `[1234:5678::abcd]` (IPv6 literal)
- `[1234:5678::abcd]:5678` (IPv6 literal with explicit port) - `[1234:5678::abcd]:5678` (IPv6 literal with explicit port)
Note {{% boxes/note %}}
This grammar is based on the standard for internet host names, as This grammar is based on the standard for internet host names, as
specified by [RFC1123, section specified by [RFC1123, section
2.1](https://tools.ietf.org/html/rfc1123#page-13), with an extension for 2.1](https://tools.ietf.org/html/rfc1123#page-13), with an extension for
IPv6 literals. IPv6 literals.
{{% /boxes/note %}}
Server names must be treated case-sensitively: in other words, Server names must be treated case-sensitively: in other words,
`@user:matrix.org` is a different person from `@user:MATRIX.ORG`. `@user:matrix.org` is a different person from `@user:MATRIX.ORG`.
@ -490,8 +490,7 @@ The complete grammar for a legal user ID is:
/ %x61-7A ; a-z / %x61-7A ; a-z
/ "-" / "." / "=" / "_" / "/" / "-" / "." / "=" / "_" / "/"
Rationale {{% boxes/rationale %}}
A number of factors were considered when defining the allowable A number of factors were considered when defining the allowable
characters for a user ID. characters for a user ID.
@ -525,6 +524,7 @@ The length restriction is derived from the limit on the length of the
`sender` key on events; since the user ID appears in every event sent by `sender` key on events; since the user ID appears in every event sent by
the user, it is limited to ensure that the user ID does not dominate the user, it is limited to ensure that the user ID does not dominate
over the actual content of the events. over the actual content of the events.
{{% /boxes/rationale %}}
Matrix user IDs are sometimes informally referred to as MXIDs. Matrix user IDs are sometimes informally referred to as MXIDs.
@ -564,12 +564,12 @@ consistently. However, we suggest the following algorithm:
well as `=`, as their hexadecimal value, prefixed with `=`. For well as `=`, as their hexadecimal value, prefixed with `=`. For
example, `#` becomes `=23`; `á` becomes `=c3=a1`. example, `#` becomes `=23`; `á` becomes `=c3=a1`.
Rationale {{% boxes/rationale %}}
The suggested mapping is an attempt to preserve human-readability of The suggested mapping is an attempt to preserve human-readability of
simple ASCII identifiers (unlike, for example, base-32), whilst still simple ASCII identifiers (unlike, for example, base-32), whilst still
allowing representation of *any* character (unlike punycode, which allowing representation of *any* character (unlike punycode, which
provides no way to encode ASCII punctuation). provides no way to encode ASCII punctuation).
{{% /boxes/rationale %}}
#### Room IDs and Event IDs #### Room IDs and Event IDs
@ -631,11 +631,11 @@ domain).
#### matrix.to navigation #### matrix.to navigation
Note {{% boxes/note %}}
This namespacing is in place pending a `matrix://` (or similar) URI This namespacing is in place pending a `matrix://` (or similar) URI
scheme. This is **not** meant to be interpreted as an available web scheme. This is **not** meant to be interpreted as an available web
service - see below for more details. service - see below for more details.
{{% /boxes/note %}}
Rooms, users, aliases, and groups may be represented as a "matrix.to" Rooms, users, aliases, and groups may be represented as a "matrix.to"
URI. This URI can be used to reference particular objects in a given URI. This URI can be used to reference particular objects in a given
@ -676,19 +676,19 @@ Examples of matrix.to URIs are:
- User: `https://matrix.to/#/%40alice%3Aexample.org` - User: `https://matrix.to/#/%40alice%3Aexample.org`
- Group: `https://matrix.to/#/%2Bexample%3Aexample.org` - Group: `https://matrix.to/#/%2Bexample%3Aexample.org`
Note {{% boxes/note %}}
Historically, clients have not produced URIs which are fully encoded. Historically, clients have not produced URIs which are fully encoded.
Clients should try to interpret these cases to the best of their Clients should try to interpret these cases to the best of their
ability. For example, an unencoded room alias should still work within ability. For example, an unencoded room alias should still work within
the client if possible. the client if possible.
{{% /boxes/note %}}
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](index.html#room-versions). These slashes should normally be
encoded when producing matrix.to URIs, however. encoded when producing matrix.to URIs, however.
{{% /boxes/note %}}
##### Routing ##### Routing

12
content/application-service-api.md
View file

@ -48,8 +48,7 @@ service.
### Registration ### Registration
Note {{% boxes/note %}}
Previously, application services could register with a homeserver via Previously, application services could register with a homeserver via
HTTP APIs. This was removed as it was seen as a security risk. A HTTP APIs. This was removed as it was seen as a security risk. A
compromised application service could re-register for a global `*` regex compromised application service could re-register for a global `*` regex
@ -58,6 +57,7 @@ application services now have to register via configuration files which
are linked to the homeserver configuration file. The addition of are linked to the homeserver configuration file. The addition of
configuration files allows homeserver admins to sanity check the configuration files allows homeserver admins to sanity check the
registration for suspicious regex strings. registration for suspicious regex strings.
{{% /boxes/note %}}
Application services register "namespaces" of user IDs, room aliases and Application services register "namespaces" of user IDs, room aliases and
room IDs. These namespaces are represented as regular expressions. An room IDs. These namespaces are represented as regular expressions. An
@ -213,12 +213,12 @@ below:
regex: "#_irc_bridge_.*" regex: "#_irc_bridge_.*"
rooms: [] rooms: []
Warning {{% boxes/warning %}}
If the homeserver in question has multiple application services, each If the homeserver in question has multiple application services, each
`as_token` and `id` MUST be unique per application service as these are `as_token` and `id` MUST be unique per application service as these are
used to identify the application service. The homeserver MUST enforce used to identify the application service. The homeserver MUST enforce
this. this.
{{% /boxes/warning %}}
### Homeserver -> Application Service API ### Homeserver -> Application Service API
@ -314,8 +314,7 @@ homeserver should retry several times before timing out. This should
result in an HTTP status 408 "Request Timeout" on the client which result in an HTTP status 408 "Request Timeout" on the client which
initiated this request (e.g. to join a room alias). initiated this request (e.g. to join a room alias).
Rationale {{% boxes/rationale %}}
Blocking the homeserver and expecting the application service to create Blocking the homeserver and expecting the application service to create
the entity using the client-server API is simpler and more flexible than the entity using the client-server API is simpler and more flexible than
alternative methods such as returning an initial sync style JSON blob alternative methods such as returning an initial sync style JSON blob
@ -323,6 +322,7 @@ and get the HS to provision the room/user. This also meant that there
didn't need to be a "backchannel" to inform the application service didn't need to be a "backchannel" to inform the application service
about information about the entity such as room ID to room alias about information about the entity such as room ID to room alias
mappings. mappings.
{{% /boxes/rationale %}}
{{query\_user\_as\_http\_api}} {{query\_user\_as\_http\_api}}

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

@ -62,11 +62,11 @@ convention of using underscores to separate words (for example
`/delete_devices`). The key names in JSON objects passed over the API `/delete_devices`). The key names in JSON objects passed over the API
also follow this convention. also follow this convention.
Note {{% boxes/note %}}
There are a few historical exceptions to this rule, such as There are a few historical exceptions to this rule, such as
`/createRoom`. A future version of this specification will address the `/createRoom`. A future version of this specification will address the
inconsistency. inconsistency.
{{% /boxes/note %}}
Any errors which occur at the Matrix API level MUST return a "standard Any errors which occur at the Matrix API level MUST return a "standard
error response". This is a JSON object which looks like: error response". This is a JSON object which looks like:
@ -296,10 +296,10 @@ conscientious decision what to do next.
### Well-known URI ### Well-known URI
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](#CORS) section in this specification.
{{% /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
specify parameter values. The flow for this method is as follows: specify parameter values. The flow for this method is as follows:
@ -344,12 +344,12 @@ 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](#Registration) processes.
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
token. Clients should treat it as an opaque byte sequence. Servers are token. Clients should treat it as an opaque byte sequence. Servers are
free to choose an appropriate format. Server implementors may like to free to choose an appropriate format. Server implementors may like to
investigate [macaroons](http://research.google.com/pubs/pub41892.html). investigate [macaroons](http://research.google.com/pubs/pub41892.html).
{{% /boxes/note %}}
### Using access tokens ### Using access tokens
@ -1096,12 +1096,12 @@ the login endpoint during the login process. For example:
##### Notes on password management ##### Notes on password management
Warning {{% boxes/warning %}}
Clients SHOULD enforce that the password provided is suitably complex. Clients SHOULD enforce that the password provided is suitably complex.
The password SHOULD include a lower-case letter, an upper-case letter, a The password SHOULD include a lower-case letter, an upper-case letter, a
number and a symbol and be at a minimum 8 characters in length. Servers number and a symbol and be at a minimum 8 characters in length. Servers
MAY reject weak passwords with an error code `M_WEAK_PASSWORD`. MAY reject weak passwords with an error code `M_WEAK_PASSWORD`.
{{% /boxes/warning %}}
### Adding Account Administrative Contact Information ### Adding Account Administrative Contact Information
@ -1109,13 +1109,13 @@ A homeserver may keep some contact information for administrative use.
This is independent of any information kept by any identity servers, This is independent of any information kept by any identity servers,
though can be proxied (bound) to the identity server in many cases. though can be proxied (bound) to the identity server in many cases.
Note {{% boxes/note %}}
This section deals with two terms: "add" and "bind". Where "add" (or This section deals with two terms: "add" and "bind". Where "add" (or
"remove") is used, it is speaking about an identifier that was not bound "remove") is used, it is speaking about an identifier that was not bound
to an identity server. As a result, "bind" (or "unbind") references an to an identity server. As a result, "bind" (or "unbind") references an
identifier that is found in an identity server. Note that an identifier identifier that is found in an identity server. Note that an identifier
can be added and bound at the same time, depending on context. can be added and bound at the same time, depending on context.
{{% /boxes/note %}}
{{administrative\_contact\_cs\_http\_api}} {{administrative\_contact\_cs\_http\_api}}
@ -1261,10 +1261,10 @@ default and only stable `available` room version.
## Pagination ## Pagination
Note {{% boxes/note %}}
The paths referred to in this section are not actual endpoints. They The paths referred to in this section are not actual endpoints. They
only serve as examples to explain how pagination functions. only serve as examples to explain how pagination functions.
{{% /boxes/note %}}
Pagination is the process of dividing a dataset into multiple discrete Pagination is the process of dividing a dataset into multiple discrete
pages. Matrix makes use of pagination to allow clients to view extremely pages. Matrix makes use of pagination to allow clients to view extremely
@ -1415,8 +1415,7 @@ any given point in time:
[E0]->[E1]->[E2]->[E3]->[E4]->[E5] [E0]->[E1]->[E2]->[E3]->[E4]->[E5]
Warning {{% boxes/warning %}}
The format of events can change depending on room version. Check the The format of events can change depending on room version. Check the
[room version specification](../index.html#room-versions) for specific [room version specification](../index.html#room-versions) for specific
details on what to expect for event formats. Examples contained within details on what to expect for event formats. Examples contained within
@ -1428,6 +1427,7 @@ the event ID format being different depending on room version. Clients
should not be parsing the event ID, and instead be treating it as an should not be parsing the event ID, and instead be treating it as an
opaque string. No changes should be required to support the currently opaque string. No changes should be required to support the currently
available room versions. available room versions.
{{% /boxes/warning %}}
### Types of room events ### Types of room events
@ -1453,13 +1453,13 @@ follow the Java package naming convention, e.g.
`com.example.myapp.event`. This ensures event types are suitably `com.example.myapp.event`. This ensures event types are suitably
namespaced for each application and reduces the risk of clashes. namespaced for each application and reduces the risk of clashes.
Note {{% boxes/note %}}
Events are not limited to the types defined in this specification. New Events are not limited to the types defined in this specification. New
or custom event types can be created on a whim using the Java package or custom event types can be created on a whim using the Java package
naming convention. For example, a `com.example.game.score` event can be naming convention. For example, a `com.example.game.score` event can be
sent by clients and other clients would receive it through Matrix, sent by clients and other clients would receive it through Matrix,
assuming the client has access to the `com.example` namespace. assuming the client has access to the `com.example` namespace.
{{% /boxes/note %}}
Note that the structure of these events may be different than those in Note that the structure of these events may be different than those in
the server-server API. the server-server API.
@ -1522,9 +1522,9 @@ than that implied by the total 65 KB limit on events.
### Room Events ### Room Events
Note {{% boxes/note %}}
This section is a work in progress. This section is a work in progress.
{{% /boxes/note %}}
This specification outlines several standard event types, all of which This specification outlines several standard event types, all of which
are prefixed with `m.` are prefixed with `m.`
@ -1607,17 +1607,16 @@ of the message timeline. The client can fill these gaps using the
prev_batch: 'd-e-f' next_batch: 'u-v-w' prev_batch: 'd-e-f' next_batch: 'u-v-w'
``` ```
Warning {{% boxes/warning %}}
Events are ordered in this API according to the arrival time of the Events are ordered in this API according to the arrival time of the
event on the homeserver. This can conflict with other APIs which order event on the homeserver. This can conflict with other APIs which order
events based on their partial ordering in the event graph. This can events based on their partial ordering in the event graph. This can
result in duplicate events being received (once per distinct API result in duplicate events being received (once per distinct API
called). Clients SHOULD de-duplicate events based on the event ID when called). Clients SHOULD de-duplicate events based on the event ID when
this happens. this happens.
{{% /boxes/warning %}}
Note {{% boxes/note %}}
The `/sync` API returns a `state` list which is separate from the The `/sync` API returns a `state` list which is separate from the
`timeline`. This `state` list allows clients to keep their model of the `timeline`. This `state` list allows clients to keep their model of the
room state in sync with that on the server. In the case of an initial room state in sync with that on the server. In the case of an initial
@ -1635,9 +1634,9 @@ In both cases, it should be noted that the events returned in the
`state` list did **not** necessarily take place just before the returned `state` list did **not** necessarily take place just before the returned
`timeline`, so clients should not display them to the user in the `timeline`, so clients should not display them to the user in the
timeline. timeline.
{{% /boxes/note %}}
Rationale {{% boxes/rationale %}}
An early design of this specification made the `state` list represent An early design of this specification made the `state` list represent
the room state at the end of the returned timeline, instead of the the room state at the end of the returned timeline, instead of the
start. This was unsatisfactory because it led to duplication of events start. This was unsatisfactory because it led to duplication of events
@ -1650,6 +1649,7 @@ where that user changes their displayname. If the `state` list
represents the room state at the end of the timeline, the client must represents the room state at the end of the timeline, the client must
take a copy of the state dictionary, and *rewind* S1, in order to take a copy of the state dictionary, and *rewind* S1, in order to
correctly calculate the display name for M0. correctly calculate the display name for M0.
{{% /boxes/rationale %}}
{{sync\_cs\_http\_api}} {{sync\_cs\_http\_api}}
@ -1739,8 +1739,7 @@ property of the redacted event, under the `redacted_because` key. When a
client receives a redaction event it should change the redacted event in client receives a redaction event it should change the redacted event in
the same way a server does. the same way a server does.
Note {{% boxes/note %}}
Redacted events can still affect the state of the room. When redacted, Redacted events can still affect the state of the room. When redacted,
state events behave as though their properties were simply not state events behave as though their properties were simply not
specified, except those protected by the redaction algorithm. For specified, except those protected by the redaction algorithm. For
@ -1748,6 +1747,7 @@ example, a redacted `join` event will still result in the user being
considered joined. Similarly, a redacted topic does not necessarily considered joined. Similarly, a redacted topic does not necessarily
cause the topic to revert to what it was prior to the event - it causes cause the topic to revert to what it was prior to the event - it causes
the topic to be removed from the room. the topic to be removed from the room.
{{% /boxes/note %}}
##### Events ##### Events
@ -1804,9 +1804,9 @@ request.
### Permissions ### Permissions
Note {{% boxes/note %}}
This section is a work in progress. This section is a work in progress.
{{% /boxes/note %}}
Permissions for rooms are done via the concept of power levels - to do Permissions for rooms are done via the concept of power levels - to do
any action in a room a user must have a suitable power level. Power any action in a room a user must have a suitable power level. Power

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

@ -194,8 +194,7 @@ process:
those already flagged as outdated, and initiates a `/keys/query`\_ those already flagged as outdated, and initiates a `/keys/query`\_
request for all of them. request for all of them.
Warning {{% boxes/warning %}}
Bob may update one of his devices while Alice has a request to Bob may update one of his devices while Alice has a request to
`/keys/query` in flight. Alice's client may therefore see Bob's user ID `/keys/query` in flight. Alice's client may therefore see Bob's user ID
in the `device_lists` field of the `/sync` response while the first in the `device_lists` field of the `/sync` response while the first
@ -218,9 +217,9 @@ each user, by queuing additional requests until the first completes.
Alternatively, the client could make a new request immediately, but Alternatively, the client could make a new request immediately, but
ensure that the first request's results are ignored (possibly by ensure that the first request's results are ignored (possibly by
cancelling the request). cancelling the request).
{{% /boxes/warning %}}
Note {{% boxes/note %}}
When Bob and Alice share a room, with Bob tracking Alice's devices, she When Bob and Alice share a room, with Bob tracking Alice's devices, she
may leave the room and then add a new device. Bob will not be notified may leave the room and then add a new device. Bob will not be notified
of this change, as he doesn't share a room anymore with Alice. When they of this change, as he doesn't share a room anymore with Alice. When they
@ -231,6 +230,7 @@ thus Bob will update his list of Alice's devices as part of his normal
processing. Note that Bob can also be notified when he stops sharing any processing. Note that Bob can also be notified when he stops sharing any
room with Alice by inspecting the `left` property of the `device_lists` room with Alice by inspecting the `left` property of the `device_lists`
field, and as a result should remove her from its list of tracked users. field, and as a result should remove her from its list of tracked users.
{{% /boxes/note %}}
##### Sending encrypted attachments ##### Sending encrypted attachments
@ -243,12 +243,12 @@ AES key, and encrypt the file using AES-CTR. The counter should be
Initialization Vector (IV), which together form a 128-bit unique counter Initialization Vector (IV), which together form a 128-bit unique counter
block. block.
Warning {{% boxes/warning %}}
An IV must never be used multiple times with the same key. This implies An IV must never be used multiple times with the same key. This implies
that if there are multiple files to encrypt in the same message, that if there are multiple files to encrypt in the same message,
typically an image and its thumbnail, the files must not share both the typically an image and its thumbnail, the files must not share both the
same key and IV. same key and IV.
{{% /boxes/warning %}}
Then, the encrypted file can be uploaded to the homeserver. The key and Then, the encrypted file can be uploaded to the homeserver. The key and
the IV must be included in the room event along with the resulting the IV must be included in the room event along with the resulting
@ -392,13 +392,13 @@ Device verification may reach one of several conclusions. For example:
reason to suspect otherwise. The encryption protocol continues to reason to suspect otherwise. The encryption protocol continues to
protect against passive eavesdroppers. protect against passive eavesdroppers.
Note {{% boxes/note %}}
Once the signing key has been verified, it is then up to the encryption Once the signing key has been verified, it is then up to the encryption
protocol to verify that a given message was sent from a device holding protocol to verify that a given message was sent from a device holding
that Ed25519 private key, or to encrypt a message so that it may only be that Ed25519 private key, or to encrypt a message so that it may only be
decrypted by such a device. For the Olm protocol, this is documented at decrypted by such a device. For the Olm protocol, this is documented at
<https://matrix.org/docs/olm_signing.html>. <https://matrix.org/docs/olm_signing.html>.
{{% /boxes/note %}}
##### Key verification framework ##### Key verification framework
@ -700,10 +700,10 @@ the info parameter is the concatenation of:
New implementations are discouraged from implementing the `curve25519` New implementations are discouraged from implementing the `curve25519`
method. method.
Rationale {{% boxes/rationale %}}
HKDF is used over the plain shared secret as it results in a harder HKDF is used over the plain shared secret as it results in a harder
attack as well as more uniform data to work with. attack as well as more uniform data to work with.
{{% /boxes/rationale %}}
For verification of each party's device keys, HKDF is as defined in RFC For verification of each party's device keys, HKDF is as defined in RFC
5869 and uses SHA-256 as the hash function. The shared secret is 5869 and uses SHA-256 as the hash function. The shared secret is
@ -746,13 +746,12 @@ following table to get the corresponding emoji:
{{sas\_emoji\_table}} {{sas\_emoji\_table}}
Note {{% boxes/note %}}
This table is available as JSON at This table is available as JSON at
<https://github.com/matrix-org/matrix-doc/blob/master/data-definitions/sas-emoji.json> <https://github.com/matrix-org/matrix-doc/blob/master/data-definitions/sas-emoji.json>
{{% /boxes/note %}}
Rationale {{% boxes/rationale %}}
The emoji above were chosen to: The emoji above were chosen to:
- Be recognisable without colour. - Be recognisable without colour.
@ -762,17 +761,18 @@ The emoji above were chosen to:
- Easily described by a few words. - Easily described by a few words.
- Avoid symbols with negative connotations. - Avoid symbols with negative connotations.
- Be likely similar across multiple platforms. - Be likely similar across multiple platforms.
{{% /boxes/rationale %}}
Clients SHOULD show the emoji with the descriptions from the table, or Clients SHOULD show the emoji with the descriptions from the table, or
appropriate translation of those descriptions. Client authors SHOULD appropriate translation of those descriptions. Client authors SHOULD
collaborate to create a common set of translations for all languages. collaborate to create a common set of translations for all languages.
Note {{% boxes/note %}}
Known translations for the emoji are available from Known translations for the emoji are available from
<https://github.com/matrix-org/matrix-doc/blob/master/data-definitions/> <https://github.com/matrix-org/matrix-doc/blob/master/data-definitions/>
and can be translated online: and can be translated online:
<https://translate.riot.im/projects/matrix-doc/sas-emoji-v1> <https://translate.riot.im/projects/matrix-doc/sas-emoji-v1>
{{% /boxes/note %}}
##### Cross-signing ##### Cross-signing
@ -950,11 +950,11 @@ indicate this by sending an [m.room\_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).
Note {{% boxes/note %}}
Key sharing can be a big attack vector, thus it must be done very Key sharing can be a big attack vector, thus it must be done very
carefully. A reasonable strategy is for a user's client to only send carefully. A reasonable strategy is for a user's client to only send
keys requested by the verified devices of the same user. keys requested by the verified devices of the same user.
{{% /boxes/note %}}
##### Server-side key backups ##### Server-side key backups
@ -1388,13 +1388,13 @@ of reasons. When this happens to an Olm-encrypted message, the client
should assume that the Olm session has become corrupted and create a new should assume that the Olm session has become corrupted and create a new
one to replace it. one to replace it.
Note {{% boxes/note %}}
Megolm-encrypted messages generally do not have the same problem. Megolm-encrypted messages generally do not have the same problem.
Usually the key for an undecryptable Megolm-encrypted message will come Usually the key for an undecryptable Megolm-encrypted message will come
later, allowing the client to decrypt it successfully. Olm does not have later, allowing the client to decrypt it successfully. Olm does not have
a way to recover from the failure, making this session replacement a way to recover from the failure, making this session replacement
process required. process required.
{{% /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](#m-dummy)
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
@ -1555,14 +1555,14 @@ difference with the `one_time_key_counts` property in the
</tbody> </tbody>
</table> </table>
Note {{% boxes/note %}}
For optimal performance, Alice should be added to `changed` in Bob's For optimal performance, Alice should be added to `changed` in Bob's
sync only when she updates her devices or cross-signing keys, or when sync only when she updates her devices or cross-signing keys, or when
Alice and Bob now share a room but didn't share any room previously. Alice and Bob now share a room but didn't share any room previously.
However, for the sake of simpler logic, a server may add Alice to However, for the sake of simpler logic, a server may add Alice to
`changed` when Alice and Bob share a new room, even if they previously `changed` when Alice and Bob share a new room, even if they previously
already shared a room. already shared a room.
{{% /boxes/note %}}
Example response: Example response:

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

@ -33,13 +33,13 @@ The four options for the `m.room.history_visibility` event are:
point they joined the room onwards. Events stop being accessible point they joined the room onwards. Events stop being accessible
when the member's state changes to something other than `join`. when the member's state changes to something other than `join`.
Warning {{% boxes/warning %}}
These options are applied at the point an event is *sent*. Checks are These options are applied at the point an event is *sent*. Checks are
performed with the state of the `m.room.history_visibility` event when performed with the state of the `m.room.history_visibility` event when
the event in question is added to the DAG. This means clients cannot the event in question is added to the DAG. This means clients cannot
retrospectively choose to show or hide history to new users if the retrospectively choose to show or hide history to new users if the
setting at that time was more restrictive. setting at that time was more restrictive.
{{% /boxes/warning %}}
#### Events #### Events

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

@ -110,11 +110,11 @@ treated similar to a `div`. Clients that support rich replies will end
up stripping the tag and its contents and therefore may wish to exclude up stripping the tag and its contents and therefore may wish to exclude
the tag entirely. the tag entirely.
Note {{% boxes/note %}}
A future iteration of the specification will support more powerful and A future iteration of the specification will support more powerful and
extensible message formatting options, such as the proposal extensible message formatting options, such as the proposal
[MSC1767](https://github.com/matrix-org/matrix-doc/pull/1767). [MSC1767](https://github.com/matrix-org/matrix-doc/pull/1767).
{{% /boxes/note %}}
{{msgtype\_events}} {{msgtype\_events}}

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

@ -18,19 +18,19 @@ any other server, similar to setting the `m.federate` value on the
{{m\_room\_server\_acl\_event}} {{m\_room\_server\_acl\_event}}
Note {{% boxes/note %}}
Port numbers are not supported because it is unclear to parsers whether Port numbers are not supported because it is unclear to parsers whether
a port number should be matched or an IP address literal. Additionally, a port number should be matched or an IP address literal. Additionally,
it is unlikely that one would trust a server running on a particular it is unlikely that one would trust a server running on a particular
domain's port but not a different port, especially considering the domain's port but not a different port, especially considering the
server host can easily change ports. server host can easily change ports.
{{% /boxes/note %}}
Note {{% boxes/note %}}
CIDR notation is not supported for IP addresses because Matrix does not CIDR notation is not supported for IP addresses because Matrix does not
encourage the use of IPs for identifying servers. Instead, a blanket encourage the use of IPs for identifying servers. Instead, a blanket
`allow_ip_literals` is provided to cover banning them. `allow_ip_literals` is provided to cover banning them.
{{% /boxes/note %}}
#### Client behaviour #### Client behaviour

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

@ -85,8 +85,7 @@ These steps are illustrated as follows:
|<-------------access token-------------| | |<-------------access token-------------| |
``` ```
Note {{% boxes/note %}}
In the older [r0.4.0 In the older [r0.4.0
version](https://matrix.org/docs/spec/client_server/r0.4.0.html#cas-based-client-login) version](https://matrix.org/docs/spec/client_server/r0.4.0.html#cas-based-client-login)
of this specification it was possible to authenticate via CAS when the of this specification it was possible to authenticate via CAS when the
@ -96,6 +95,7 @@ which is the same process with the only change being which redirect
endpoint to use: for `m.login.cas`, use `/cas/redirect` and for endpoint to use: for `m.login.cas`, use `/cas/redirect` and for
`m.login.sso` use `/sso/redirect` (described below). The endpoints are `m.login.sso` use `/sso/redirect` (described below). The endpoints are
otherwise the same. otherwise the same.
{{% /boxes/note %}}
##### Client behaviour ##### Client behaviour

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

@ -254,10 +254,10 @@ characteristics than the service's long-term keys.
### Client behaviour ### Client behaviour
Note {{% boxes/note %}}
This section only covers the v2 lookup endpoint. The v1 endpoint is This section only covers the v2 lookup endpoint. The v1 endpoint is
described in isolation above. described in isolation above.
{{% /boxes/note %}}
Prior to performing a lookup clients SHOULD make a request to the Prior to performing a lookup clients SHOULD make a request to the
`/hash_details` endpoint to determine what algorithms the server `/hash_details` endpoint to determine what algorithms the server
@ -269,10 +269,10 @@ Clients MUST support at least the `sha256` algorithm.
### Server behaviour ### Server behaviour
Note {{% boxes/note %}}
This section only covers the v2 lookup endpoint. The v1 endpoint is This section only covers the v2 lookup endpoint. The v1 endpoint is
described in isolation above. described in isolation above.
{{% /boxes/note %}}
Servers, upon receipt of a `/lookup` request, will compare the query Servers, upon receipt of a `/lookup` request, will compare the query
against known bindings it has, hashing the identifiers it knows about as against known bindings it has, hashing the identifiers it knows about as
@ -299,11 +299,11 @@ the 3PID to search for. For example, if the client wanted to know about
`alice@example.org`'s bindings, it would first format the query as `alice@example.org`'s bindings, it would first format the query as
`alice@example.org email ThePepperGoesHere`. `alice@example.org email ThePepperGoesHere`.
Rationale {{% boxes/rationale %}}
Mediums and peppers are appended to the address to prevent a common Mediums and peppers are appended to the address to prevent a common
prefix for each 3PID, helping prevent attackers from pre-computing the prefix for each 3PID, helping prevent attackers from pre-computing the
internal state of the hash function. internal state of the hash function.
{{% /boxes/rationale %}}
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
@ -342,12 +342,12 @@ the client has made an appropriate request to `/hash_details` first.
### Security considerations ### Security considerations
Note {{% boxes/note %}}
[MSC2134](https://github.com/matrix-org/matrix-doc/pull/2134) has much [MSC2134](https://github.com/matrix-org/matrix-doc/pull/2134) has much
more information about the security considerations made for this section more information about the security considerations made for this section
of the specification. This section covers the high-level details for why of the specification. This section covers the high-level details for why
the specification is the way it is. the specification is the way it is.
{{% /boxes/note %}}
Typically the lookup endpoint is used when a client has an unknown 3PID Typically the lookup endpoint is used when a client has an unknown 3PID
it wants to find a Matrix User ID for. Clients normally do this kind of it wants to find a Matrix User ID for. Clients normally do this kind of
@ -359,8 +359,7 @@ protect the privacy of users who might not have a Matrix identifier
bound to their 3PID addresses, the specification attempts to make it bound to their 3PID addresses, the specification attempts to make it
difficult to harvest 3PIDs. difficult to harvest 3PIDs.
Rationale {{% boxes/rationale %}}
Hashing identifiers, while not perfect, helps make the effort required Hashing identifiers, while not perfect, helps make the effort required
to harvest identifiers significantly higher. Phone numbers in particular to harvest identifiers significantly higher. Phone numbers in particular
are still difficult to protect with hashing, however hashing is are still difficult to protect with hashing, however hashing is
@ -369,6 +368,7 @@ objectively better than not.
An alternative to hashing would be using bcrypt or similar with many An alternative to hashing would be using bcrypt or similar with many
rounds, however by nature of needing to serve mobile clients and clients rounds, however by nature of needing to serve mobile clients and clients
on limited hardware the solution needs be kept relatively lightweight. on limited hardware the solution needs be kept relatively lightweight.
{{% /boxes/rationale %}}
Clients should be cautious of servers not rotating their pepper very Clients should be cautious of servers not rotating their pepper very
often, and potentially of servers which use a weak pepper - these often, and potentially of servers which use a weak pepper - these

20
content/rooms/v1.md
View file

@ -46,30 +46,29 @@ of one of the following event types:
## Server implementation components ## Server implementation components
Warning {{% boxes/warning %}}
The information contained in this section is strictly for server The information contained in this section is strictly for server
implementors. Applications which use the Client-Server API are generally implementors. Applications which use the Client-Server API are generally
unaffected by the intricacies contained here. The section above unaffected by the intricacies contained here. The section above
regarding client considerations is the resource that Client-Server API regarding client considerations is the resource that Client-Server API
use cases should reference. use cases should reference.
{{% /boxes/warning %}}
The algorithms defined here should only apply to version 1 rooms. Other The algorithms defined here should only apply to version 1 rooms. Other
algorithms may be used by other room versions, and as such servers algorithms may be used by other room versions, and as such servers
should be aware of which version room they are dealing with prior to should be aware of which version room they are dealing with prior to
executing a given algorithm. executing a given algorithm.
Warning {{% boxes/warning %}}
Although there are many rooms using room version 1, it is known to have Although there are many rooms using room version 1, it is known to have
undesirable effects. Servers implementing support for room version 1 undesirable effects. Servers implementing support for room version 1
should be aware that restrictions should be generally relaxed and that should be aware that restrictions should be generally relaxed and that
inconsistencies may occur. inconsistencies may occur.
{{% /boxes/warning %}}
### State resolution ### State resolution
Warning {{% boxes/warning %}}
Room version 1 is known to have bugs that can cause the state of rooms Room version 1 is known to have bugs that can cause the state of rooms
to reset to older versions of the room's state. For example this could to reset to older versions of the room's state. For example this could
mean that users who had joined the room may be removed from the room, mean that users who had joined the room may be removed from the room,
@ -79,6 +78,7 @@ as the the room's name or topic could also reset to a previous version.
This is fixed in the state resolution algorithm introduced in room This is fixed in the state resolution algorithm introduced in room
version 2. version 2.
{{% /boxes/warning %}}
The room state *S*′(*E*) after an event *E* is defined in terms of the The room state *S*′(*E*) after an event *E* is defined in terms of the
room state *S*(*E*) before *E*, and depends on whether *E* is a state room state *S*(*E*) before *E*, and depends on whether *E* is a state
@ -135,11 +135,11 @@ The types of state events that affect authorization are:
- `m.room.power_levels` - `m.room.power_levels`
- `m.room.third_party_invite` - `m.room.third_party_invite`
Note {{% boxes/note %}}
Power levels are inferred from defaults when not explicitly supplied. Power levels are inferred from defaults when not explicitly supplied.
For example, mentions of the `sender`'s power level can also refer to For example, mentions of the `sender`'s power level can also refer to
the default power level for users in the room. the default power level for users in the room.
{{% /boxes/note %}}
The rules are as follows: The rules are as follows:
@ -261,8 +261,7 @@ The rules are as follows:
3. Otherwise, reject. 3. Otherwise, reject.
12. Otherwise, allow. 12. Otherwise, allow.
Note {{% boxes/note %}}
Some consequences of these rules: Some consequences of these rules:
- Unless you are a member of the room, the only permitted operations - Unless you are a member of the room, the only permitted operations
@ -271,6 +270,7 @@ Some consequences of these rules:
- To unban somebody, you must have power level greater than or equal - To unban somebody, you must have power level greater than or equal
to both the kick *and* ban levels, *and* greater than the target to both the kick *and* ban levels, *and* greater than the target
user's power level. user's power level.
{{% /boxes/note %}}
### Event format ### Event format

8
content/rooms/v2.md
View file

@ -9,12 +9,12 @@ state resolution algorithm.
## Server implementation components ## Server implementation components
Warning {{% boxes/warning %}}
The information contained in this section is strictly for server The information contained in this section is strictly for server
implementors. Applications which use the Client-Server API are generally implementors. Applications which use the Client-Server API are generally
unaffected by the details contained here, and can safely ignore their unaffected by the details contained here, and can safely ignore their
presence. presence.
{{% /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](v1.html),
changing only the state resolution algorithm. changing only the state resolution algorithm.
@ -157,8 +157,7 @@ chain should appear in the process, as they should not appear in state
(the algorithm only uses events that appear in either the state sets or (the algorithm only uses events that appear in either the state sets or
in the auth chain of the events in the state sets). in the auth chain of the events in the state sets).
Rationale {{% boxes/rationale %}}
This helps ensure that different servers' view of state is more likely This helps ensure that different servers' view of state is more likely
to converge, since rejection state of an event may be different. This to converge, since rejection state of an event may be different. This
can happen if a third server gives an incorrect version of the state can happen if a third server gives an incorrect version of the state
@ -182,6 +181,7 @@ Intuitively, using rejected events feels dangerous, however:
the event. The duplicated event would then pass the auth checks. the event. The duplicated event would then pass the auth checks.
Ignoring rejected events would therefore not eliminate any potential Ignoring rejected events would therefore not eliminate any potential
attack vectors. attack vectors.
{{% /boxes/rationale %}}
Rejected auth events are deliberately excluded from use in the iterative Rejected auth events are deliberately excluded from use in the iterative
auth checks, as auth events aren't re-authed (although non-auth events auth checks, as auth events aren't re-authed (although non-auth events

8
content/rooms/v3.md
View file

@ -22,21 +22,20 @@ and the potentially problematic slash).
## Server implementation components ## Server implementation components
Warning {{% boxes/warning %}}
The information contained in this section is strictly for server The information contained in this section is strictly for server
implementors. Applications which use the Client-Server API are generally implementors. Applications which use the Client-Server API are generally
unaffected by the intricacies contained here. The section above unaffected by the intricacies contained here. The section above
regarding client considerations is the resource that Client-Server API regarding client considerations is the resource that Client-Server API
use cases should reference. use cases should reference.
{{% /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](v2.html), and the event format defined here.
### Event IDs ### Event IDs
Rationale {{% boxes/rationale %}}
In other room versions (namely version 1 and 2) the event ID is a In other room versions (namely version 1 and 2) the event ID is a
distinct field from the remainder of the event, which must be tracked as distinct field from the remainder of the event, which must be tracked as
such. This leads to complications where servers receive multiple events such. This leads to complications where servers receive multiple events
@ -44,6 +43,7 @@ with the same ID in either the same or different rooms where the server
cannot easily keep track of which event it should be using. By removing cannot easily keep track of which event it should be using. By removing
the use of a dedicated event ID, servers are required to track the the use of a dedicated event ID, servers are required to track the
hashes on an event to determine its ID. hashes on an event to determine its ID.
{{% /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/%SERVER_RELEASE_LABEL%.html#reference-hashes) of

8
content/rooms/v4.md
View file

@ -21,26 +21,26 @@ domain).
## Server implementation components ## Server implementation components
Warning {{% boxes/warning %}}
The information contained in this section is strictly for server The information contained in this section is strictly for server
implementors. Applications which use the Client-Server API are generally implementors. Applications which use the Client-Server API are generally
unaffected by the intricacies contained here. The section above unaffected by the intricacies contained here. The section above
regarding client considerations is the resource that Client-Server API regarding client considerations is the resource that Client-Server API
use cases should reference. use cases should reference.
{{% /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](v3.html), however using URL-safe base64 to generate the event ID.
### Event IDs ### Event IDs
Rationale {{% boxes/rationale %}}
Room version 3 generated event IDs that were difficult for client Room version 3 generated event IDs that were difficult for client
implementations which were not encoding the event ID to function in implementations which were not encoding the event ID to function in
those rooms. It additionally raised concern due to the `/` character those rooms. It additionally raised concern due to the `/` character
being interpretted differently by some reverse proxy software, and being interpretted differently by some reverse proxy software, and
generally made administration harder. generally made administration harder.
{{% /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/%SERVER_RELEASE_LABEL%.html#reference-hashes) of

4
content/rooms/v5.md
View file

@ -15,13 +15,13 @@ Clients should be aware of event ID changes in [room version
## Server implementation components ## Server implementation components
Warning {{% boxes/warning %}}
The information contained in this section is strictly for server The information contained in this section is strictly for server
implementors. Applications which use the Client-Server API are generally implementors. Applications which use the Client-Server API are generally
unaffected by the intricacies contained here. The section above unaffected by the intricacies contained here. The section above
regarding client considerations is the resource that Client-Server API regarding client considerations is the resource that Client-Server API
use cases should reference. use cases should reference.
{{% /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](v4.html), ensuring that signing key validity is respected.

4
content/rooms/v6.md
View file

@ -16,13 +16,13 @@ otherwise unchanged.
## Server implementation components ## Server implementation components
Warning {{% boxes/warning %}}
The information contained in this section is strictly for server The information contained in this section is strictly for server
implementors. Applications which use the Client-Server API are generally implementors. Applications which use the Client-Server API are generally
unaffected by the intricacies contained here. The section above unaffected by the intricacies contained here. The section above
regarding client considerations is the resource that Client-Server API regarding client considerations is the resource that Client-Server API
use cases should reference. use cases should reference.
{{% /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](v5.html).

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

@ -184,12 +184,12 @@ Transparency](https://www.certificate-transparency.org/) project.
### Retrieving server keys ### Retrieving server keys
Note {{% boxes/note %}}
There was once a "version 1" of the key exchange. It has been removed There was once a "version 1" of the key exchange. It has been removed
from the specification due to lack of significance. It may be reviewed from the specification due to lack of significance. It may be reviewed
[from the historical [from the historical
draft](https://github.com/matrix-org/matrix-doc/blob/51faf8ed2e4a63d4cfd6d23183698ed169956cc0/specification/server_server_api.rst#232version-1). draft](https://github.com/matrix-org/matrix-doc/blob/51faf8ed2e4a63d4cfd6d23183698ed169956cc0/specification/server_server_api.rst#232version-1).
{{% /boxes/note %}}
Each homeserver publishes its public keys under Each homeserver publishes its public keys under
`/_matrix/key/v2/server/{keyId}`. Homeservers query for keys by either `/_matrix/key/v2/server/{keyId}`. Homeservers query for keys by either
@ -451,21 +451,20 @@ rejected event where it is a state event.
If an event in an incoming transaction is rejected, this should not If an event in an incoming transaction is rejected, this should not
cause the transaction request to be responded to with an error response. cause the transaction request to be responded to with an error response.
Note {{% boxes/note %}}
This means that events may be included in the room DAG even though they This means that events may be included in the room DAG even though they
should be rejected. should be rejected.
{{% /boxes/note %}}
Note {{% boxes/note %}}
This is in contrast to redacted events which can still affect the state This is in contrast to redacted events which can still affect the state
of the room. For example, a redacted `join` event will still result in of the room. For example, a redacted `join` event will still result in
the user being considered joined. the user being considered joined.
{{% /boxes/note %}}
#### Soft failure #### Soft failure
Rationale {{% boxes/rationale %}}
It is important that we prevent users from evading bans (or other power It is important that we prevent users from evading bans (or other power
restrictions) by creating events which reference old parts of the DAG. restrictions) by creating events which reference old parts of the DAG.
For example, a banned user could continue to send messages to a room by For example, a banned user could continue to send messages to a room by
@ -486,6 +485,7 @@ clients about the new event.
This discourages servers from sending events that evade bans etc. in This discourages servers from sending events that evade bans etc. in
this way, as end users won't actually see the events. this way, as end users won't actually see the events.
{{% /boxes/rationale %}}
When the homeserver receives a new event over federation it should also When the homeserver receives a new event over federation it should also
check whether the event passes auth checks based on the current state of check whether the event passes auth checks based on the current state of
@ -499,28 +499,28 @@ nor be referenced by new events created by the homeserver (i.e. they
should not be added to the server's list of forward extremities of the should not be added to the server's list of forward extremities of the
room). Soft failed events are otherwise handled as usual. room). Soft failed events are otherwise handled as usual.
Note {{% boxes/note %}}
Soft failed events participate in state resolution as normal if further Soft failed events participate in state resolution as normal if further
events are received which reference it. It is the job of the state events are received which reference it. It is the job of the state
resolution algorithm to ensure that malicious events cannot be injected resolution algorithm to ensure that malicious events cannot be injected
into the room state via this mechanism. into the room state via this mechanism.
{{% /boxes/note %}}
Note {{% boxes/note %}}
Because soft failed state events participate in state resolution as Because soft failed state events participate in state resolution as
normal, it is possible for such events to appear in the current state of normal, it is possible for such events to appear in the current state of
the room. In that case the client should be told about the soft failed the room. In that case the client should be told about the soft failed
event in the usual way (e.g. by sending it down in the `state` section event in the usual way (e.g. by sending it down in the `state` section
of a sync response). of a sync response).
{{% /boxes/note %}}
Note {{% boxes/note %}}
A soft failed event should be returned in response to federation A soft failed event should be returned in response to federation
requests where appropriate (e.g. in `/event/<event_id>`). Note that soft requests where appropriate (e.g. in `/event/<event_id>`). Note that soft
failed events are returned in `/backfill` and `/get_missing_events` failed events are returned in `/backfill` and `/get_missing_events`
responses only if the requests include events referencing the soft responses only if the requests include events referencing the soft
failed events. failed events.
{{% /boxes/note %}}
Example Example
@ -783,11 +783,11 @@ the event to other servers in the room.
## Third-party invites ## Third-party invites
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/%CLIENT_RELEASE_LABEL%.html) under
the Third Party Invites module. the Third Party Invites module.
{{% /boxes/note %}}
When a user wants to invite another user in a room but doesn't know the When a user wants to invite another user in a room but doesn't know the
Matrix ID to invite, they can do so using a third-party identifier (e.g. Matrix ID to invite, they can do so using a third-party identifier (e.g.

20
layouts/partials/alert.html Normal file
View file

@ -0,0 +1,20 @@
{{/*
Display an alert box of the given type, containing the given content.
Supported types are "warning", "info", and "rationale".
The type determines the colors used in the box and, by default,
the title for the box: WARNING, INFO, RATIONALE.
By passing "omit_title", a caller can suppress the title, and just get
a box using the colors and styles for the given type.
*/}}
{{ $type := .type}}
{{ $content := .content}}
{{ $omit_title := .omit_title }}
<div class="alert {{ $type }} {{ if $omit_title }}omit-title{{end}}" role="alert">
{{ $content | markdownify }}
</div>

1
layouts/shortcodes/boxes/note.html Normal file
View file

@ -0,0 +1 @@
{{ partial "alert" (dict "type" "note" "content" .Inner) }}

1
layouts/shortcodes/boxes/rationale.html Normal file
View file

@ -0,0 +1 @@
{{ partial "alert" (dict "type" "rationale" "content" .Inner) }}

1
layouts/shortcodes/boxes/warning.html Normal file
View file

@ -0,0 +1 @@
{{ partial "alert" (dict "type" "warning" "content" .Inner) }}