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

Room versions 8 and 9: Restricted rooms (#3387)

Browse source 
* Room versions 8 and 9: Restricted rooms

MSCs:
* https://github.com/matrix-org/matrix-doc/pull/3083
* https://github.com/matrix-org/matrix-doc/pull/3289
* https://github.com/matrix-org/matrix-doc/pull/3375

* Changelogs

* Capitalization

Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com>

* Remove verbiage for spaces because they don't exist

* Iterations on text

* Another clarification

* Make error code descriptions consistent

* Apply suggestions from code review

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* Incorporate from merge

* Misc language update per review

* Update accuracy before splitting auth rules

* fix wtf moment

* Fix up v8 and v9 to match "fully specify room versions"

* Scope auth events selection to room version

* Apply consistency

* Add changelogs

* Review part 1

* Apply suggestions from code review

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* Split out redaction sections

* Clarify general case of join conditions

Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
This commit is contained in:
Travis Ralston 2022-01-18 09:55:34 -07:00 • committed by GitHub
parent 3475ef62ab
commit 6c4aabd053
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
22 changed files with 772 additions and 39 deletions
Download patch file Download diff file Expand all files Collapse all files

11
content/rooms/_index.md
View file

@ -36,9 +36,10 @@ Alternatively, consider flipping the column/row organization to be features
up top and versions on the left.
-->
| Feature \ Version | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
|-------------------|---|---|---|---|---|---|---|
| **Knocking** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ |
| Feature \ Version | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |
|-------------------|---|---|---|---|---|---|---|---|---|
| **Knocking** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ | ✔ | ✔ |
| **Restricted join rules** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ | ✔ |
## Complete list of room versions
@ -68,6 +69,10 @@ The available room versions are:
- [Version 6](/rooms/v6) - **Stable**. Alters several
authorization rules for events.
- [Version 7](/rooms/v7) - **Stable**. Introduces knocking.
- [Version 8](/rooms/v8) - **Stable**. Adds a join rule to allow members
of another room to join without invite.
- [Version 9](/rooms/v9) - **Stable**. Builds on v8 to fix issues when
redacting some membership events.
## Room version grammar

160
content/rooms/fragments/v8-auth-rules.md Normal file
View file

@ -0,0 +1,160 @@
---
toc_hide: true
---
Events must be signed by the server denoted by the `sender` key.
`m.room.redaction` events are not explicitly part of the auth rules.
They are still subject to the minimum power level rules, but should always
fall into "10. Otherwise, allow". Instead of being authorized at the time
of receipt, they are authorized at a later stage: see the
[Redactions](#redactions) section below for more information.
The types of state events that affect authorization are:
- `m.room.create`
- `m.room.member`
- `m.room.join_rules`
- `m.room.power_levels`
- `m.room.third_party_invite`
{{% 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:
1. If type is `m.room.create`:
1. If it has any previous events, reject.
2. If the domain of the `room_id` does not match the domain of the
`sender`, reject.
3. If `content.room_version` is present and is not a recognised
version, reject.
4. If `content` has no `creator` field, reject.
5. Otherwise, allow.
2. Reject if event has `auth_events` that:
1. have duplicate entries for a given `type` and `state_key` pair
2. have entries whose `type` and `state_key` don't match those
specified by the [auth events
selection](/server-server-api#auth-events-selection)
algorithm described in the server specification.
3. If event does not have a `m.room.create` in its `auth_events`,
reject.
4. If type is `m.room.member`:
1. If no `state_key` key or `membership` key in `content`, reject.
2. If `content` has a `join_authorised_via_users_server`
key:
1. If the event is not validly signed by the user ID denoted
by the key, reject.
3. If `membership` is `join`:
1. If the only previous event is an `m.room.create` and the
`state_key` is the creator, allow.
2. If the `sender` does not match `state_key`, reject.
3. If the `sender` is banned, reject.
4. If the `join_rule` is `invite` then allow if membership
state is `invite` or `join`.
5. If the `join_rule` is `restricted`:
1. If membership state is `join` or `invite`, allow.
2. If the `join_authorised_via_users_server` key in `content`
is not a user with sufficient permission to invite other
users, reject.
3. Otherwise, allow.
6. If the `join_rule` is `public`, allow.
7. Otherwise, reject.
4. If `membership` is `invite`:
1. If `content` has `third_party_invite` key:
1. If *target user* is banned, reject.
2. If `content.third_party_invite` does not have a `signed`
key, reject.
3. If `signed` does not have `mxid` and `token` keys,
reject.
4. If `mxid` does not match `state_key`, reject.
5. If there is no `m.room.third_party_invite` event in the
current room state with `state_key` matching `token`,
reject.
6. If `sender` does not match `sender` of the
`m.room.third_party_invite`, reject.
7. If any signature in `signed` matches any public key in
the `m.room.third_party_invite` event, allow. The public
keys are in `content` of `m.room.third_party_invite` as:
1. A single public key in the `public_key` field.
2. A list of public keys in the `public_keys` field.
8. Otherwise, reject.
2. If the `sender`'s current membership state is not `join`,
reject.
3. If *target user*'s current membership state is `join` or
`ban`, reject.
4. If the `sender`'s power level is greater than or equal to
the *invite level*, allow.
5. Otherwise, reject.
5. If `membership` is `leave`:
1. If the `sender` matches `state_key`, allow if and only if
that user's current membership state is `invite` or `join`.
2. If the `sender`'s current membership state is not `join`,
reject.
3. If the *target user*'s current membership state is `ban`,
and the `sender`'s power level is less than the *ban level*,
reject.
4. If the `sender`'s power level is greater than or equal to
the *kick level*, and the *target user*'s power level is
less than the `sender`'s power level, allow.
5. Otherwise, reject.
6. If `membership` is `ban`:
1. If the `sender`'s current membership state is not `join`,
reject.
2. If the `sender`'s power level is greater than or equal to
the *ban level*, and the *target user*'s power level is less
than the `sender`'s power level, allow.
3. Otherwise, reject.
7. If `membership` is `knock`:
1. If the `join_rule` is anything other than `knock`, reject.
2. If `sender` does not match `state_key`, reject.
3. If the `sender`'s current membership is not `ban`, `invite`,
or `join`, allow.
8. Otherwise, the membership is unknown. Reject.
5. If the `sender`'s current membership state is not `join`, reject.
6. If type is `m.room.third_party_invite`:
1. Allow if and only if `sender`'s current power level is greater
than or equal to the *invite level*.
7. If the event type's *required power level* is greater than the
`sender`'s power level, reject.
8. If the event has a `state_key` that starts with an `@` and does not
match the `sender`, reject.
9. If type is `m.room.power_levels`:
1. If `users` key in `content` is not a dictionary with keys that
are valid user IDs with values that are integers (or a string
that is an integer), reject.
2. If there is no previous `m.room.power_levels` event in the room,
allow.
3. For the keys `users_default`, `events_default`, `state_default`,
`ban`, `redact`, `kick`, `invite` check if they were added,
changed or removed. For each found alteration:
1. If the current value is higher than the `sender`'s current
power level, reject.
2. If the new value is higher than the `sender`'s current power
level, reject.
4. For each entry being added, changed or removed in both the
`events`, `users`, and `notifications` keys:
1. If the current value is higher than the `sender`'s current
power level, reject.
2. If the new value is higher than the `sender`'s current power
level, reject.
5. For each entry being changed under the `users` key, other than
the `sender`'s own entry:
1. If the current value is equal to the `sender`'s current
power level, reject.
6. Otherwise, allow.
10. Otherwise, allow.
{{% boxes/note %}}
Some consequences of these rules:
- Unless you are a member of the room, the only permitted operations
(apart from the initial create/join) are: joining a public room;
accepting or rejecting an invitation to a room.
- 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 %}}

6
content/rooms/v7.md
View file

@ -199,6 +199,10 @@ completeness.
{{% rver-fragment name="v4-event-format" %}}
### Handling redactions
{{% rver-fragment name="v3-handling-redactions" %}}
### Canonical JSON
{{% rver-fragment name="v6-canonical-json" %}}
@ -209,6 +213,4 @@ completeness.
### Redactions
{{% rver-fragment name="v3-handling-redactions" %}}
{{% rver-fragment name="v6-redactions" %}}

123
content/rooms/v8.md Normal file
View file

@ -0,0 +1,123 @@
---
title: Room Version 8
type: docs
weight: 60
---
This room version builds on [version 7](/rooms/v7) to introduce a new
join rule that allows members to join the room based on membership in
another room.
{{% boxes/warning %}}
This room version is known to have issues relating to redactions of member
join events. [Room version 9](/rooms/v9) should be preferred over v8 when
creating rooms.
{{% /boxes/warning %}}
## Client considerations
Clients are encouraged to expose the option for the join rule in their
user interface for supported room versions.
The new join rule, `restricted`, is described in the
[Client-Server API](/client-server-api/#restricted-rooms).
Clients which implement the redaction algorithm locally should refer to the
[redactions](#redactions) section below for a full overview.
### Redactions
{{% added-in this=true %}} `m.room.join_rules` events now keep `allow` in addition to other
keys in `content` when being redacted.
{{% boxes/warning %}}
[Room version 9](/rooms/v9) adds additional cases of protected properties for behaviour
related to restricted rooms (the functionality introduced in v8). v9 is preferred over
v8 when creating new rooms.
{{% /boxes/warning %}}
The full redaction algorithm follows.
Upon receipt of a redaction event, the server must strip off any keys
not in the following list:
- `event_id`
- `type`
- `room_id`
- `sender`
- `state_key`
- `content`
- `hashes`
- `signatures`
- `depth`
- `prev_events`
- `prev_state`
- `auth_events`
- `origin`
- `origin_server_ts`
- `membership`
The content object must also be stripped of all keys, unless it is one
of one of the following event types:
- `m.room.member` allows key `membership`.
- `m.room.create` allows key `creator`.
- `m.room.join_rules` allows keys `join_rule`, `allow`.
- `m.room.power_levels` allows keys `ban`, `events`, `events_default`,
`kick`, `redact`, `state_default`, `users`, `users_default`.
- `m.room.history_visibility` allows key `history_visibility`.
## Server implementation components
{{% 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 8 adds a new join rule to allow members of a room to join another
room without invite. Otherwise, the room version inherits all properties of
[Room version 7](/rooms/v7).
### Authorization rules
{{% added-in this=true %}} For checks performed upon `m.room.member` events, new
points for handling `content.join_authorised_via_users_server` are added (Rule 4.2
and 4.3.5).
{{% rver-fragment name="v8-auth-rules" %}}
### Redactions
[See above](#redactions).
## Unchanged from v7
The following sections have not been modified since v7, but are included for
completeness.
### State resolution
{{% rver-fragment name="v2-state-res" %}}
### Event IDs
{{% rver-fragment name="v4-event-ids" %}}
### Event format
{{% rver-fragment name="v4-event-format" %}}
### Handling redactions
{{% rver-fragment name="v3-handling-redactions" %}}
### Canonical JSON
{{% rver-fragment name="v6-canonical-json" %}}
### Signing key validity period
{{% rver-fragment name="v5-signing-requirements" %}}

119
content/rooms/v9.md Normal file
View file

@ -0,0 +1,119 @@
---
title: Room Version 9
type: docs
weight: 60
---
This room version builds on [version 8](/rooms/v8) to add additional redaction
rules that were unintentionally missed when incorporating v8.
## Client considerations
See [room version 8](/rooms/v8) for specific details regarding the addition of
restricted rooms.
Clients which implement the redaction algorithm locally should refer to the
[redactions](#redactions) section below for a full overview.
### Redactions
{{% added-in this=true %}} `m.room.member` now keep `join_authorised_via_users_server`
in addition to other keys in `content` when being redacted.
{{% boxes/rationale %}}
Without the `join_authorised_via_users_server` property, redacted join events
can become invalid when verifying the auth chain of a given event, thus creating
a split-brain scenario where the user is able to speak from one server's
perspective but most others will continually reject their events.
This can theoretically be worked around with a rejoin to the room, being careful
not to use the faulty events as `prev_events`, though instead it is encouraged
to use v9 rooms over v8 rooms to outright avoid the situation.
[Issue #3373](https://github.com/matrix-org/matrix-doc/issues/3373) has further
information.
{{% /boxes/rationale %}}
The full redaction algorithm follows.
{{% rver-fragment name="v3-handling-redactions" %}}
Upon receipt of a redaction event, the server must strip off any keys
not in the following list:
- `event_id`
- `type`
- `room_id`
- `sender`
- `state_key`
- `content`
- `hashes`
- `signatures`
- `depth`
- `prev_events`
- `prev_state`
- `auth_events`
- `origin`
- `origin_server_ts`
- `membership`
The content object must also be stripped of all keys, unless it is one
of one of the following event types:
- `m.room.member` allows keys `membership`, `join_authorised_via_users_server`.
- `m.room.create` allows key `creator`.
- `m.room.join_rules` allows keys `join_rule`, `allow`.
- `m.room.power_levels` allows keys `ban`, `events`, `events_default`,
`kick`, `redact`, `state_default`, `users`, `users_default`.
- `m.room.history_visibility` allows key `history_visibility`.
## Server implementation components
{{% 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 8 added a new `restricted` join rule to allow members of a room
to join another room without invite. Room version 9 is based upon v8 with the
following considerations.
### Redactions
[See above](#redactions).
## Unchanged from v8
The following sections have not been modified since v8, but are included for
completeness.
### State resolution
{{% rver-fragment name="v2-state-res" %}}
### Authorization rules
{{% rver-fragment name="v8-auth-rules" %}}
### Event IDs
{{% rver-fragment name="v4-event-ids" %}}
### Event format
{{% rver-fragment name="v4-event-format" %}}
### Handling redactions
{{% rver-fragment name="v3-handling-redactions" %}}
### Canonical JSON
{{% rver-fragment name="v6-canonical-json" %}}
### Signing key validity period
{{% rver-fragment name="v5-signing-requirements" %}}