Support alerts (notes, warnings, rationales)
This commit is contained in:
Will
parent
ab64bda76d
commit
338434bfcd
22 changed files with 194 additions and 138 deletions
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue