MSC1772 defines Spaces: a new way to define groups of users and rooms in Matrix by describing them as a room. Originally MSC1772 attempted to define how you could apply permissions to Matrix rooms based on the membership of a space. However, this is effectively a separate concern from how you model spaces themselves, and so has been split out into a this separate MSC.
This MSC originally included restricting room membership based on space membership. This has been split into MSC3083.
Thus, the goal of this MSC is to set the power levels in a room based on membership of a space.
One use-case for spaces is to help manage power levels across a group of rooms. For example: "Jim has just joined the management team at my company. He should have moderator rights across all of the company rooms."
Since the event-authorisation rules cannot easily be extended to consider
membership in other rooms, we must map any changes in space membership onto
real m.room.power_levels events.
We now have a mix of manually- and automatically- maintained power-level
data. To support this, we extend the existing m.room.power_levels event to
add an auto_users key:
{
"type": "m.room.power_levels",
"content": {
"users": {
"@roomadmin:example.com": 100
},
"auto_users": {
"@spaceuser1:example.org": 50
}
}
}A user's power level is then specified by an entry in either users or
auto_users. Where a user appears in both sections, users takes precedence.
The new auto_users key is maintained by a bot user, as described below.
auto_users is subject to all of the same authorization checks as the existing
users key (see https://matrix.org/docs/spec/rooms/v1#authorization-rules,
paragraphs 10a, 10d, 10e).
This change necessitates a new room version.
The desired mapping from spaces to power levels is defined in a new state
event type, m.room.power_level_mappings, set in the room whose PLs are being
manipulated. The content should contain a mappings key which is an
ordered list, for example:
{
"type": "m.room.power_level_mappings",
"state_key": "",
"content": {
"mappings": [
{
"space": "!mods:example.org",
"via": ["example.org"],
"power_level": 50
},
{
"space": "!users:example.org",
"via": ["example.org"],
"power_level": 1
}
]
}
}This means that a new m.room.power_levels event would be generated whenever
the membership of either !mods or !users changes. If a user is in both
spaces, !mods takes priority because that is listed first.
If mappings is not a list, the whole event is ignored. Any entries in the list
which do not match the expected format are ignored.
When a new room is created, the server implicitly adds a "room admin bot" to the room, with the maximum power-level of any of the initial users. (Homeservers should implement this "bot" internally, rather than requiring separate software to be installed.)
It is proposed that this "admin bot" use the special user ID with empty
localpart @:example.com.
This bot is then responsible for monitoring the power_level_mappings state,
and peeking into any spaces mentioned in the content. It can then issue new
m.room.power_levels events, updating the value of auto_users, whenever the
membership of the spaces in question changes.
It is possible that the admin bot is unable to perform the mapping (for
example, the space cannot be peeked; or the membership of the space is so large
that it cannot be expanded into a single m.room.power_levels event). It is
proposed that the bot could notify the room of any problems via
m.room.message messages of type m.msgtype.
Clearly, updating this event type is extremely powerful. It is expected that
access to it is itself restricted via power_levels. This could be enforced by
the admin bot so that no m.room.power_levels events are generated unless
power_level_mappings is appropriately restricted.
Some sort of rate-limiting may be required to handle the case where the mapped space has a high rate of membership churn.
Things that were considered and dismissed:
-
Extend the auth rules to include state from other rooms. Although this feels cleaner, a robust implementation would be a hugely complicated undertaking. In particular, room state resolution is closely linked to event authorisation, and is already highly complex and hard to reason about, and yet is fundamental to the security of Matrix.
In short, we believe such a change would require significant research and modelling. A solution based on such a foundation could not practically be implemented in the near future.
-
Rather than defining the mapping in the room, define a template power-levels event in a parent space, which will be inherited by all child rooms. For example:
{ "type": "m.space.child_power_levels", "state_key": "", "content": { // content as per regular power_levels event } }
Problem 1: No automated mapping from space membership to user list, so the user list would have to be maintained manually. On the other hand, this could be fine in some situations, where we're just using the space to group together rooms, rather than as a user list.
Problem 2: No scope for nuance, where different rooms have slightly different PLs.
Problem 3: what happens to rooms where several spaces claim it as a child? They end up fighting?
Problem 4: Doesn't allow for random room admins to delegate their PLs to a space without being admins in that space.
-
To implement the mapping, we require any user who is an admin in the space (ie, anyone who has permission to change the access rights in the space) to also be admins and members of any child rooms.
Say Bob is an admin in #doglovers and makes a change that should be propagated to all children of that space. His server is then responsible for generating a power-levels event on his behalf for each room.
Problem 1: Bob may not want to be a member of all such rooms.
Problem 2: It will feel odd that Bob's user is seen to be generating PL events every time someone comes and goes from the space.
Problem 3: It doesn't allow users to set up their own rooms to mirror a space, without having any particular control in that space (though it is questionable if that is actually a useful feature, at least as far as PLs are concerned.)
-
Another alternative for implementing the mapping: the user that created the relationship event (or rather, their homeserver, using the user's ID) is responsible for copying access controls into the room.
Problem 1: What do you do if the admin who sets up the PL relationship disappears? The humans have to step in and create a new admin?
Problem 2: Again it seems odd that these PL changes come from a single user.
-
Is it possible to implement the mappings from multiple users, some of which may not have PL 100? After all it's possible to set rooms up so that you can change PL events without having PL 100.
It gets horribly messy very quickly, where some admin users can make some changes. So some get supressed and then get made later anyway by a different admin user?
-
Is it possble to apply finer-grained control to the
m.room.power_level_mappingsevent than "you must be max(PL)"? Applying restrictions post-hoc (ie, having the admin bot ignore settings which were set by underpriviledged users) is an absolute minefield. It might be possible to apply restrictions at the point that the event is set, but it sounds fiddly and it's not clear there is a real use-case. -
This solution smells a bit funny because of the expansions (causing all the redundant mxids everywhere as the groups constantly get expanded every time something happens).
-
Could we could put a hash of the space membership in the PL instead of expanding the whole list, so that servers have a way to check if they are applying the same list as everyone else?
Feels like it will have bad failure modes: what is a server supposed to do when the hash doesn't match?
-
Could version the space memberships, so you can compare with the source of the space membership data?
-
PL events just record the delta from the previous one? (So a new server would need to get all the PLs ever, but… is that a bad thing?) ... maybe
These optimisations can all be punted down the road to a later room version.
-
-
Other ways of handling the merge of automatic and manual PL settings:
-
Add hints to the automated mapper so that it can maintain manually-assigned PLs. This could either be another field in
power_levelswhich plays no part in event auth:{ "type": "m.room.power_levels", "content": { "users": { "@roomadmin:example.com": 100, "@spaceuser1:example.org": 50 }, "manual_users": { "@roomadmin:example.com": 100 } } }
... or stored in a separate event. Clients would be responsible for updating both copies of the manually-assigned PLs on change.
Problem: Requiring clients to make two changes feels fragile. What if they get it wrong? what if they don't know about the second copy because they haven't been designed to work in rooms in spaces?
-
Require that even regular PLs go through the automated mapper, by making them an explicit input to that mapper, for example with entries in the
m.room.power_level_mappingsevent suggested above.Problem: Requires clients to distinguish between rooms where there is an automated mapper, and those where the client should manipulate the PLs directly. (Maybe that's not so bad? The presence of the
mappingsevent should be enough? But still sucks that there are two ways to do the same thing, and clients which don't support spaces will get it wrong.)
-
- MSC1772 for room spaces.
- The peek server has significant power. For example, a poorly chosen peek
server could lie about the space membership and add an
@evil_user:example.org.
The following mapping will be used for identifiers in this MSC during development:
| Proposed final identifier | Purpose | Development identifier |
|---|---|---|
m.room.power_level_mappings |
event type | org.matrix.msc1772.room.power_level_mappings |
auto_users |
key in m.room.power_levels event |
org.matrix.msc1772.auto_users |