Support alerts (notes, warnings, rationales)

pull/977/head
Will 4 years ago
parent ab64bda76d
commit 338434bfcd
No known key found for this signature in database
GPG Key ID: 385872BB265E8BF8

@ -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 */
/* Update link colours for MAtrix style */

@ -35,13 +35,13 @@ browsing the Client-Server API.
### Matrix versions
Note
{{% boxes/note %}}
As of June 10th 2019, the Matrix specification is considered out of beta
-indicating that all currently released APIs are considered stable and
secure to the best of our knowledge, and the spec should contain the
complete information necessary to develop production-grade
implementations of Matrix without the need for external reference.
{{% /boxes/note %}}
Matrix 1.0 (released June 10th, 2019) consists of the following minimum
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
other servers participating in a room.
Note
{{% boxes/note %}}
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
naming convention. For example, a `com.example.game.score` event can be
sent by clients and other clients would receive it through Matrix,
assuming the client has access to the `com.example` namespace.
{{% /boxes/note %}}
#### Room Aliases

@ -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
represent all numbers using this representation.
Warning
{{% boxes/warning %}}
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
which is considered invalid by these restrictions where possible.
The most notable consideration is that integers might not be in the
range specified above.
{{% /boxes/warning %}}
Note
{{% boxes/note %}}
Float values are not permitted by this encoding.
{{% /boxes/note %}}
```py
import json
@ -415,12 +415,12 @@ Examples of valid server names are:
- `[1234:5678::abcd]` (IPv6 literal)
- `[1234:5678::abcd]:5678` (IPv6 literal with explicit port)
Note
{{% boxes/note %}}
This grammar is based on the standard for internet host names, as
specified by [RFC1123, section
2.1](https://tools.ietf.org/html/rfc1123#page-13), with an extension for
IPv6 literals.
{{% /boxes/note %}}
Server names must be treated case-sensitively: in other words,
`@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
/ "-" / "." / "=" / "_" / "/"
Rationale
{{% boxes/rationale %}}
A number of factors were considered when defining the allowable
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
the user, it is limited to ensure that the user ID does not dominate
over the actual content of the events.
{{% /boxes/rationale %}}
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
example, `#` becomes `=23`; `á` becomes `=c3=a1`.
Rationale
{{% boxes/rationale %}}
The suggested mapping is an attempt to preserve human-readability of
simple ASCII identifiers (unlike, for example, base-32), whilst still
allowing representation of *any* character (unlike punycode, which
provides no way to encode ASCII punctuation).
{{% /boxes/rationale %}}
#### Room IDs and Event IDs
@ -631,11 +631,11 @@ domain).
#### matrix.to navigation
Note
{{% boxes/note %}}
This namespacing is in place pending a `matrix://` (or similar) URI
scheme. This is **not** meant to be interpreted as an available web
service - see below for more details.
{{% /boxes/note %}}
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
@ -676,19 +676,19 @@ Examples of matrix.to URIs are:
- User: `https://matrix.to/#/%40alice%3Aexample.org`
- Group: `https://matrix.to/#/%2Bexample%3Aexample.org`
Note
{{% boxes/note %}}
Historically, clients have not produced URIs which are fully encoded.
Clients should try to interpret these cases to the best of their
ability. For example, an unencoded room alias should still work within
the client if possible.
{{% /boxes/note %}}
Note
{{% boxes/note %}}
Clients should be aware that decoding a matrix.to URI may result in
extra slashes appearing due to some [room
versions](index.html#room-versions). These slashes should normally be
encoded when producing matrix.to URIs, however.
{{% /boxes/note %}}
##### Routing

@ -48,8 +48,7 @@ service.
### Registration
Note
{{% boxes/note %}}
Previously, application services could register with a homeserver via
HTTP APIs. This was removed as it was seen as a security risk. A
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
configuration files allows homeserver admins to sanity check the
registration for suspicious regex strings.
{{% /boxes/note %}}
Application services register "namespaces" of user IDs, room aliases and
room IDs. These namespaces are represented as regular expressions. An
@ -213,12 +213,12 @@ below:
regex: "#_irc_bridge_.*"
rooms: []
Warning
{{% boxes/warning %}}
If the homeserver in question has multiple application services, each
`as_token` and `id` MUST be unique per application service as these are
used to identify the application service. The homeserver MUST enforce
this.
{{% /boxes/warning %}}
### 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
initiated this request (e.g. to join a room alias).
Rationale
{{% boxes/rationale %}}
Blocking the homeserver and expecting the application service to create
the entity using the client-server API is simpler and more flexible than
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
about information about the entity such as room ID to room alias
mappings.
{{% /boxes/rationale %}}
{{query\_user\_as\_http\_api}}

@ -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
also follow this convention.
Note
{{% boxes/note %}}
There are a few historical exceptions to this rule, such as
`/createRoom`. A future version of this specification will address the
inconsistency.
{{% /boxes/note %}}
Any errors which occur at the Matrix API level MUST return a "standard
error response". This is a JSON object which looks like:
@ -296,10 +296,10 @@ conscientious decision what to do next.
### Well-known URI
Note
{{% boxes/note %}}
Servers hosting the `.well-known` JSON file SHOULD offer CORS headers,
as per the [CORS](#CORS) section in this specification.
{{% /boxes/note %}}
The `.well-known` method uses a JSON file at a predetermined location to
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
[Registration](#Registration) processes.
Note
{{% boxes/note %}}
This specification does not mandate a particular format for the access
token. Clients should treat it as an opaque byte sequence. Servers are
free to choose an appropriate format. Server implementors may like to
investigate [macaroons](http://research.google.com/pubs/pub41892.html).
{{% /boxes/note %}}
### Using access tokens
@ -1096,12 +1096,12 @@ the login endpoint during the login process. For example:
##### Notes on password management
Warning
{{% boxes/warning %}}
Clients SHOULD enforce that the password provided is suitably complex.
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
MAY reject weak passwords with an error code `M_WEAK_PASSWORD`.
{{% /boxes/warning %}}
### 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,
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
"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
identifier that is found in an identity server. Note that an identifier
can be added and bound at the same time, depending on context.
{{% /boxes/note %}}
{{administrative\_contact\_cs\_http\_api}}
@ -1261,10 +1261,10 @@ default and only stable `available` room version.
## Pagination
Note
{{% boxes/note %}}
The paths referred to in this section are not actual endpoints. They
only serve as examples to explain how pagination functions.
{{% /boxes/note %}}
Pagination is the process of dividing a dataset into multiple discrete
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]
Warning
{{% boxes/warning %}}
The format of events can change depending on room version. Check the
[room version specification](../index.html#room-versions) for specific
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
opaque string. No changes should be required to support the currently
available room versions.
{{% /boxes/warning %}}
### 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
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
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
sent by clients and other clients would receive it through Matrix,
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
the server-server API.
@ -1522,9 +1522,9 @@ than that implied by the total 65 KB limit on events.
### Room Events
Note
{{% boxes/note %}}
This section is a work in progress.
{{% /boxes/note %}}
This specification outlines several standard event types, all of which
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'
```
Warning
{{% boxes/warning %}}
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
events based on their partial ordering in the event graph. This can
result in duplicate events being received (once per distinct API
called). Clients SHOULD de-duplicate events based on the event ID when
this happens.
{{% /boxes/warning %}}
Note
{{% boxes/note %}}
The `/sync` API returns a `state` list which is separate from 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
@ -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
`timeline`, so clients should not display them to the user in the
timeline.
{{% /boxes/note %}}
Rationale
{{% boxes/rationale %}}
An early design of this specification made the `state` list represent
the room state at the end of the returned timeline, instead of the
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
take a copy of the state dictionary, and *rewind* S1, in order to
correctly calculate the display name for M0.
{{% /boxes/rationale %}}
{{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
the same way a server does.
Note
{{% boxes/note %}}
Redacted events can still affect the state of the room. When redacted,
state events behave as though their properties were simply not
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
cause the topic to revert to what it was prior to the event - it causes
the topic to be removed from the room.
{{% /boxes/note %}}
##### Events
@ -1804,9 +1804,9 @@ request.
### Permissions
Note
{{% boxes/note %}}
This section is a work in progress.
{{% /boxes/note %}}
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

@ -194,8 +194,7 @@ process:
those already flagged as outdated, and initiates a `/keys/query`\_
request for all of them.
Warning
{{% boxes/warning %}}
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
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
ensure that the first request's results are ignored (possibly by
cancelling the request).
{{% /boxes/warning %}}
Note
{{% boxes/note %}}
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
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
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.
{{% /boxes/note %}}
##### 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
block.
Warning
{{% boxes/warning %}}
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,
typically an image and its thumbnail, the files must not share both the
same key and IV.
{{% /boxes/warning %}}
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
@ -392,13 +392,13 @@ Device verification may reach one of several conclusions. For example:
reason to suspect otherwise. The encryption protocol continues to
protect against passive eavesdroppers.
Note
{{% boxes/note %}}
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
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
<https://matrix.org/docs/olm_signing.html>.
{{% /boxes/note %}}
##### Key verification framework
@ -700,10 +700,10 @@ the info parameter is the concatenation of:
New implementations are discouraged from implementing the `curve25519`
method.
Rationale
{{% boxes/rationale %}}
HKDF is used over the plain shared secret as it results in a harder
attack as well as more uniform data to work with.
{{% /boxes/rationale %}}
For verification of each party's device keys, HKDF is as defined in RFC
5869 and uses SHA-256 as the hash function. The shared secret is
@ -746,13 +746,12 @@ following table to get the corresponding emoji:
{{sas\_emoji\_table}}
Note
{{% boxes/note %}}
This table is available as JSON at
<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:
- Be recognisable without colour.
@ -762,17 +761,18 @@ The emoji above were chosen to:
- Easily described by a few words.
- Avoid symbols with negative connotations.
- Be likely similar across multiple platforms.
{{% /boxes/rationale %}}
Clients SHOULD show the emoji with the descriptions from the table, or
appropriate translation of those descriptions. Client authors SHOULD
collaborate to create a common set of translations for all languages.
Note
{{% boxes/note %}}
Known translations for the emoji are available from
<https://github.com/matrix-org/matrix-doc/blob/master/data-definitions/>
and can be translated online:
<https://translate.riot.im/projects/matrix-doc/sas-emoji-v1>
{{% /boxes/note %}}
##### 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
withheld](#reporting-that-decryption-keys-are-withheld).
Note
{{% boxes/note %}}
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
keys requested by the verified devices of the same user.
{{% /boxes/note %}}
##### 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
one to replace it.
Note
{{% boxes/note %}}
Megolm-encrypted messages generally do not have the same problem.
Usually the key for an undecryptable Megolm-encrypted message will come
later, allowing the client to decrypt it successfully. Olm does not have
a way to recover from the failure, making this session replacement
process required.
{{% /boxes/note %}}
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
@ -1555,14 +1555,14 @@ difference with the `one_time_key_counts` property in the
</tbody>
</table>
Note
{{% boxes/note %}}
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
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
`changed` when Alice and Bob share a new room, even if they previously
already shared a room.
{{% /boxes/note %}}
Example response:

@ -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
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
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
retrospectively choose to show or hide history to new users if the
setting at that time was more restrictive.
{{% /boxes/warning %}}
#### Events

@ -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
the tag entirely.
Note
{{% boxes/note %}}
A future iteration of the specification will support more powerful and
extensible message formatting options, such as the proposal
[MSC1767](https://github.com/matrix-org/matrix-doc/pull/1767).
{{% /boxes/note %}}
{{msgtype\_events}}

@ -18,19 +18,19 @@ any other server, similar to setting the `m.federate` value on the
{{m\_room\_server\_acl\_event}}
Note
{{% boxes/note %}}
Port numbers are not supported because it is unclear to parsers whether
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
domain's port but not a different port, especially considering the
server host can easily change ports.
{{% /boxes/note %}}
Note
{{% boxes/note %}}
CIDR notation is not supported for IP addresses because Matrix does not
encourage the use of IPs for identifying servers. Instead, a blanket
`allow_ip_literals` is provided to cover banning them.
{{% /boxes/note %}}
#### Client behaviour

@ -85,8 +85,7 @@ These steps are illustrated as follows:
|<-------------access token-------------| |
```
Note
{{% boxes/note %}}
In the older [r0.4.0
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
@ -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
`m.login.sso` use `/sso/redirect` (described below). The endpoints are
otherwise the same.
{{% /boxes/note %}}
##### Client behaviour

@ -254,10 +254,10 @@ characteristics than the service's long-term keys.
### Client behaviour
Note
{{% boxes/note %}}
This section only covers the v2 lookup endpoint. The v1 endpoint is
described in isolation above.
{{% /boxes/note %}}
Prior to performing a lookup clients SHOULD make a request to the
`/hash_details` endpoint to determine what algorithms the server
@ -269,10 +269,10 @@ Clients MUST support at least the `sha256` algorithm.
### Server behaviour
Note
{{% boxes/note %}}
This section only covers the v2 lookup endpoint. The v1 endpoint is
described in isolation above.
{{% /boxes/note %}}
Servers, upon receipt of a `/lookup` request, will compare the query
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 email ThePepperGoesHere`.
Rationale
{{% boxes/rationale %}}
Mediums and peppers are appended to the address to prevent a common
prefix for each 3PID, helping prevent attackers from pre-computing the
internal state of the hash function.
{{% /boxes/rationale %}}
After formatting each query, the string is run through SHA-256 as
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
Note
{{% boxes/note %}}
[MSC2134](https://github.com/matrix-org/matrix-doc/pull/2134) has much
more information about the security considerations made for this section
of the specification. This section covers the high-level details for why
the specification is the way it is.
{{% /boxes/note %}}
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
@ -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
difficult to harvest 3PIDs.
Rationale
{{% boxes/rationale %}}
Hashing identifiers, while not perfect, helps make the effort required
to harvest identifiers significantly higher. Phone numbers in particular
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
rounds, however by nature of needing to serve mobile clients and clients
on limited hardware the solution needs be kept relatively lightweight.
{{% /boxes/rationale %}}
Clients should be cautious of servers not rotating their pepper very
often, and potentially of servers which use a weak pepper - these

@ -46,30 +46,29 @@ of one of the following event types:
## Server implementation components
Warning
{{% boxes/warning %}}
The information contained in this section is strictly for server
implementors. Applications which use the Client-Server API are generally
unaffected by the intricacies contained here. The section above
regarding client considerations is the resource that Client-Server API
use cases should reference.
{{% /boxes/warning %}}
The algorithms defined here should only apply to version 1 rooms. Other
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
executing a given algorithm.
Warning
{{% boxes/warning %}}
Although there are many rooms using room version 1, it is known to have
undesirable effects. Servers implementing support for room version 1
should be aware that restrictions should be generally relaxed and that
inconsistencies may occur.
{{% /boxes/warning %}}
### State resolution
Warning
{{% boxes/warning %}}
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
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
version 2.
{{% /boxes/warning %}}
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
@ -135,11 +135,11 @@ The types of state events that affect authorization are:
- `m.room.power_levels`
- `m.room.third_party_invite`
Note
{{% boxes/note %}}
Power levels are inferred from defaults when not explicitly supplied.
For example, mentions of the `sender`'s power level can also refer to
the default power level for users in the room.
{{% /boxes/note %}}
The rules are as follows:
@ -261,8 +261,7 @@ The rules are as follows:
3. Otherwise, reject.
12. Otherwise, allow.
Note
{{% boxes/note %}}
Some consequences of these rules:
- 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 both the kick *and* ban levels, *and* greater than the target
user's power level.
{{% /boxes/note %}}
### Event format

@ -9,12 +9,12 @@ state resolution algorithm.
## Server implementation components
Warning
{{% boxes/warning %}}
The information contained in this section is strictly for server
implementors. Applications which use the Client-Server API are generally
unaffected by the details contained here, and can safely ignore their
presence.
{{% /boxes/warning %}}
Room version 2 uses the base components of [room version 1](v1.html),
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
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
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
@ -182,6 +181,7 @@ Intuitively, using rejected events feels dangerous, however:
the event. The duplicated event would then pass the auth checks.
Ignoring rejected events would therefore not eliminate any potential
attack vectors.
{{% /boxes/rationale %}}
Rejected auth events are deliberately excluded from use in the iterative
auth checks, as auth events aren't re-authed (although non-auth events

@ -22,21 +22,20 @@ and the potentially problematic slash).
## Server implementation components
Warning
{{% boxes/warning %}}
The information contained in this section is strictly for server
implementors. Applications which use the Client-Server API are generally
unaffected by the intricacies contained here. The section above
regarding client considerations is the resource that Client-Server API
use cases should reference.
{{% /boxes/warning %}}
Room version 3 uses the state resolution algorithm defined in [room
version 2](v2.html), and the event format defined here.
### Event IDs
Rationale
{{% boxes/rationale %}}
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
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
the use of a dedicated event ID, servers are required to track the
hashes on an event to determine its ID.
{{% /boxes/rationale %}}
The event ID is the [reference
hash](../server_server/%SERVER_RELEASE_LABEL%.html#reference-hashes) of

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

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

@ -16,13 +16,13 @@ otherwise unchanged.
## Server implementation components
Warning
{{% boxes/warning %}}
The information contained in this section is strictly for server
implementors. Applications which use the Client-Server API are generally
unaffected by the intricacies contained here. The section above
regarding client considerations is the resource that Client-Server API
use cases should reference.
{{% /boxes/warning %}}
Room version 6 makes the following alterations to algorithms described
in [room version 5](v5.html).

@ -184,12 +184,12 @@ Transparency](https://www.certificate-transparency.org/) project.
### Retrieving server keys
Note
{{% boxes/note %}}
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 historical
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
`/_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
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
should be rejected.
{{% /boxes/note %}}
Note
{{% boxes/note %}}
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
the user being considered joined.
{{% /boxes/note %}}
#### Soft failure
Rationale
{{% boxes/rationale %}}
It is important that we prevent users from evading bans (or other power
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
@ -486,6 +485,7 @@ clients about the new event.
This discourages servers from sending events that evade bans etc. in
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
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
room). Soft failed events are otherwise handled as usual.
Note
{{% boxes/note %}}
Soft failed events participate in state resolution as normal if further
events are received which reference it. It is the job of the state
resolution algorithm to ensure that malicious events cannot be injected
into the room state via this mechanism.
{{% /boxes/note %}}
Note
{{% boxes/note %}}
Because soft failed state events participate in state resolution as
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
event in the usual way (e.g. by sending it down in the `state` section
of a sync response).
{{% /boxes/note %}}
Note
{{% boxes/note %}}
A soft failed event should be returned in response to federation
requests where appropriate (e.g. in `/event/<event_id>`). Note that soft
failed events are returned in `/backfill` and `/get_missing_events`
responses only if the requests include events referencing the soft
failed events.
{{% /boxes/note %}}
Example
@ -783,11 +783,11 @@ the event to other servers in the room.
## Third-party invites
Note
{{% boxes/note %}}
More information about third party invites is available in the
[Client-Server API](../client_server/%CLIENT_RELEASE_LABEL%.html) under
the Third Party Invites module.
{{% /boxes/note %}}
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.

@ -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>

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

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

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