Specify room version 10: `knock_restricted` and int power levels (#1099)
* Clarification on historical power level handling
* Revert "Clarification on historical power level handling"
This reverts commit f443b3d5a9.
* Clean up
* Let us try this again not using VS Code
* Markdown is full of mysteries
* Move stringy power levels to room versions
* Describe range
* Fix minor issues with previous room version stuff
* Copy/paste v9 into v10
* Describe deprecated formatting
* Paste unmodified auth rules from v8 into v10
* Move 9.1 to 9.3, add 9.1 and 9.2 for integer enforcement
* Add knock_restricted to v10 auth
* Misc cleanup and clarification for fragments
* Describe `knock_restricted` client changes
* Changelogs
* spelling
* Apply suggestions from code review
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
* Apply code review suggestions manually
* Fix v9 redactions
* Fix auth rules clarity issues
* Apply suggestions from code review
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
* Remove false integer requirements
Co-authored-by: Neil Alexander <neilalexander@users.noreply.github.com>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
pull/1114/head
Travis Ralston
3 years ago
committed by
GitHub
parent
e70045f4cc
commit
f14e18131b
@ -0,0 +1 @@
|
|||||||
|
Add support for a new `knock_restricted` join rule in supported room versions, as per [MSC3787](https://github.com/matrix-org/matrix-spec-proposals/pull/3787).
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Clarify that room versions 1 through 9 accept stringy power levels, as noted by [MSC3667](https://github.com/matrix-org/matrix-spec-proposals/pull/3667).
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Add room version 10 as per [MSC3604](https://github.com/matrix-org/matrix-spec-proposals/pull/3604).
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Enforce integer power levels in room version 10 as per [MSC3667](https://github.com/matrix-org/matrix-spec-proposals/pull/3667).
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Add a `knock_restricted` join rule supported by room version 10 as per [MSC3787](https://github.com/matrix-org/matrix-spec-proposals/pull/3787).
|
||||||
@ -0,0 +1 @@
|
|||||||
|
Clarify the historical handling of non-integer power levels.
|
||||||
@ -0,0 +1,13 @@
|
|||||||
|
---
|
||||||
|
toc_hide: true
|
||||||
|
---
|
||||||
|
|
||||||
|
Events sent into rooms of this version can have formats which are different
|
||||||
|
from their normal schema. Those cases are documented here.
|
||||||
|
|
||||||
|
{{% boxes/warning %}}
|
||||||
|
The behaviour described here is preserved strictly for backwards compatibility
|
||||||
|
only. A homeserver should take reasonable precautions to prevent users from
|
||||||
|
sending these so-called "malformed" events, and must never rely on the behaviours
|
||||||
|
described here as a default.
|
||||||
|
{{% /boxes/warning %}}
|
||||||
@ -0,0 +1,43 @@
|
|||||||
|
---
|
||||||
|
toc_hide: true
|
||||||
|
---
|
||||||
|
|
||||||
|
##### `m.room.power_levels` events accept values as strings
|
||||||
|
|
||||||
|
In order to maintain backwards compatibility with early implementations,
|
||||||
|
each of the integer-valued properties within
|
||||||
|
[`m.room.power_levels`](/client-server-api#mroompower_levels) events can
|
||||||
|
be encoded as strings instead of integers. This includes the nested values
|
||||||
|
within the `events`, `notifications` and `users` properties.
|
||||||
|
For example, the following is a valid `m.room.power_levels` event in this room version:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"content": {
|
||||||
|
"ban": "50",
|
||||||
|
"events": {
|
||||||
|
"m.room.power_levels": "100"
|
||||||
|
},
|
||||||
|
"events_default": "0",
|
||||||
|
"state_default": "50",
|
||||||
|
"users": {
|
||||||
|
"@example:localhost": "100"
|
||||||
|
},
|
||||||
|
"users_default": "0"
|
||||||
|
},
|
||||||
|
"origin_server_ts": 1432735824653,
|
||||||
|
"room_id": "!jEsUZKDJdhlrceRyVU:example.org",
|
||||||
|
"sender": "@example:example.org",
|
||||||
|
"state_key": "",
|
||||||
|
"type": "m.room.power_levels"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
When the value is representative of an integer, they must be the following format:
|
||||||
|
|
||||||
|
* a single base 10 integer, no float values or decimal points, optionally with
|
||||||
|
any number of leading zeroes (`"100"`, `"000100"`);
|
||||||
|
* optionally prefixed with a single `-` or `+` character before the integer (`"+100"`,
|
||||||
|
`"-100"`).
|
||||||
|
* optionally with any number of leading or trailing whitespace characters (`" 100 "`,
|
||||||
|
`" 00100 "`, `" +100 "`, `" -100 "`);
|
||||||
@ -0,0 +1,51 @@
|
|||||||
|
---
|
||||||
|
toc_hide: true
|
||||||
|
---
|
||||||
|
|
||||||
|
{{% added-in this=true %}} `m.room.member` events 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.
|
||||||
|
|
||||||
|
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`.
|
||||||
@ -0,0 +1,277 @@
|
|||||||
|
---
|
||||||
|
title: Room Version 10
|
||||||
|
type: docs
|
||||||
|
weight: 100
|
||||||
|
---
|
||||||
|
|
||||||
|
This room version builds on [version 9](/rooms/v9) to enforce that power level
|
||||||
|
values be integers, and to introduce a new `knock_restricted` join rule, allowing
|
||||||
|
prospective members to more easily join such a room.
|
||||||
|
|
||||||
|
## Client considerations
|
||||||
|
|
||||||
|
This room version adds a new `knock_restricted` join rule to allow prospective
|
||||||
|
members of a room join either through knocking (introduced in [room version 7](/rooms/v7))
|
||||||
|
or through "join restrictions" (introduced in [room version 8](/rooms/v8) and
|
||||||
|
refined in [room version 9](/rooms/v9)).
|
||||||
|
|
||||||
|
Clients should render the new join rule accordingly for such rooms. For example:
|
||||||
|
|
||||||
|
```
|
||||||
|
This room is:
|
||||||
|
[ ] Public
|
||||||
|
[x] Private
|
||||||
|
|
||||||
|
Join rules (disabled when Public):
|
||||||
|
[x] Allow members of `#space:example.org` to join
|
||||||
|
[x] Allow knocking
|
||||||
|
```
|
||||||
|
|
||||||
|
Clients which implement the redaction algorithm locally should refer to the
|
||||||
|
[redactions](#redactions) section below for a full overview.
|
||||||
|
|
||||||
|
## 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 7](/rooms/v7) added "knocking" and [room version 8](/rooms/v8)
|
||||||
|
added "join restrictions" (refined by [room version 9](/rooms/v9)) — both allow
|
||||||
|
prospective members an avenue to join, however it was not possible to use
|
||||||
|
the two mechanisms together. This room version adds a new
|
||||||
|
`knock_restricted` join rule as a mix of the two behaviours, allowing a user to
|
||||||
|
join the room if they meet either the `restricted` join rule criteria or the
|
||||||
|
`knock` join rule criteria.
|
||||||
|
|
||||||
|
This room version additionally requires that values in the power levels event
|
||||||
|
be integers and not string representations, unlike other room versions.
|
||||||
|
|
||||||
|
Room version 10 is based upon room version 9 with the following considerations.
|
||||||
|
|
||||||
|
### Event format
|
||||||
|
|
||||||
|
The event format is unchanged by this room version. See [below](#event-format-1)
|
||||||
|
for details on the current event format.
|
||||||
|
|
||||||
|
#### Deprecated event content schemas
|
||||||
|
|
||||||
|
While this room version does not change the event format specifically, some
|
||||||
|
deprecated behaviours are strictly no longer supported.
|
||||||
|
|
||||||
|
##### Values in `m.room.power_levels` events must be integers
|
||||||
|
|
||||||
|
In other room versions, such as [v9](/rooms/v9/#mroompower_levels-events-accept-values-as-strings),
|
||||||
|
power levels could be represented as strings for backwards compatibility.
|
||||||
|
|
||||||
|
This backwards compatibility is removed in this room version - power levels MUST NOT
|
||||||
|
be represented as strings within this room version. Power levels which are not
|
||||||
|
correctly structured are rejected under the authorization rules below.
|
||||||
|
|
||||||
|
### Authorization rules
|
||||||
|
|
||||||
|
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`](/client-server-api#mroomcreate)
|
||||||
|
- [`m.room.member`](/client-server-api#mroommember)
|
||||||
|
- [`m.room.join_rules`](/client-server-api#mroom)
|
||||||
|
- [`m.room.power_levels`](/client-server-api#mroompower_levels)
|
||||||
|
- [`m.room.third_party_invite`](/client-server-api#mroomthird_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 homeserver of 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` or `knock` then allow if
|
||||||
|
membership state is `invite` or `join`.
|
||||||
|
5. {{< changed-in this="true" >}}
|
||||||
|
If the `join_rule` is `restricted` or `knock_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`, `join`,
|
||||||
|
or `knock`.
|
||||||
|
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. {{< changed-in this="true" >}}
|
||||||
|
If the `join_rule` is anything other than `knock` or
|
||||||
|
`knock_restricted`, reject.
|
||||||
|
2. If `sender` does not match `state_key`, reject.
|
||||||
|
3. If the `sender`'s current membership is not `ban`, `invite`,
|
||||||
|
or `join`, allow.
|
||||||
|
4. Otherwise, reject.
|
||||||
|
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. {{< added-in this="true" >}}
|
||||||
|
If any of the keys `users_default`, `events_default`, `state_default`,
|
||||||
|
`ban`, `redact`, `kick`, or `invite` in `content` are present and
|
||||||
|
not an integer, reject.
|
||||||
|
2. {{< added-in this="true" >}}
|
||||||
|
If either of the keys `events` or `notifications` in `content`
|
||||||
|
are present and not a dictionary with values that are integers,
|
||||||
|
reject.
|
||||||
|
3. If `users` key in `content` is not a dictionary with keys that
|
||||||
|
are valid user IDs with values that are integers, 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 %}}
|
||||||
|
|
||||||
|
## Unchanged from v9
|
||||||
|
|
||||||
|
The following sections have not been modified since v9, but are included for
|
||||||
|
completeness.
|
||||||
|
|
||||||
|
### Redactions
|
||||||
|
|
||||||
|
{{% rver-fragment name="v9-redactions" %}}
|
||||||
|
|
||||||
|
### Handling redactions
|
||||||
|
|
||||||
|
{{% rver-fragment name="v3-handling-redactions" %}}
|
||||||
|
|
||||||
|
### Event IDs
|
||||||
|
|
||||||
|
{{% rver-fragment name="v4-event-ids" %}}
|
||||||
|
|
||||||
|
### Event format
|
||||||
|
|
||||||
|
{{% rver-fragment name="v4-event-format" %}}
|
||||||
|
|
||||||
|
### State resolution
|
||||||
|
|
||||||
|
{{% rver-fragment name="v2-state-res" %}}
|
||||||
|
|
||||||
|
### Canonical JSON
|
||||||
|
|
||||||
|
{{% rver-fragment name="v6-canonical-json" %}}
|
||||||
|
|
||||||
|
### Signing key validity period
|
||||||
|
|
||||||
|
{{% rver-fragment name="v5-signing-requirements" %}}
|
||||||
Loading…
Reference in New Issue