Room Version 1
This room version is the first ever version for rooms, and contains the building blocks for other room versions.
Client considerations
Clients which implement the redaction algorithm locally should refer to the redactions section below.
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 the following event types:
m.room.member
allows keymembership
.m.room.create
allows keycreator
.m.room.join_rules
allows keyjoin_rule
.m.room.power_levels
allows keysban
,events
,events_default
,kick
,redact
,state_default
,users
,users_default
.m.room.aliases
allows keyaliases
.m.room.history_visibility
allows keyhistory_visibility
.
Server implementation components
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.
Redactions
Event IDs
An event has exactly one event ID. Event IDs in this room version have the format:
$opaque_id:domain
where domain
is the server name of the homeserver
which created the room, and opaque_id
is a locally-unique string.
The domain is used only for namespacing to avoid the risk of clashes of identifiers between different homeservers. There is no implication that the room or event in question is still available at the corresponding homeserver.
Event format
Events in version 1 rooms have the following structure:
Persistent Data Unit
Persistent Data Unit
A persistent data unit (event) for room versions 1 and 2.
Name | Type | Description |
---|---|---|
auth_events |
[array] |
Required: Event IDs and reference hashes for the authorization events that would allow this event to be in the room. Must contain less than or equal to 10 events. Note that if the relevant auth event selection rules are used, this restriction should never be encountered. |
content |
object |
Required: The content of the event. |
depth |
integer |
Required: The maximum depth of the prev_events , plus one. Must be less than the
maximum value for an integer (2^63 - 1). If the room’s depth is already at
the limit, the depth must be set to the limit. |
event_id |
string |
Required: The event ID for the PDU. |
hashes |
Event Hash |
Required: Content hashes of the PDU, following the algorithm specified in Signing Events. |
origin_server_ts |
integer |
Required: Timestamp in milliseconds on origin homeserver when this event was created. |
prev_events |
[array] |
Required: Event IDs and reference hashes for the most recent events in the room that the homeserver was aware of when it made this event. Must contain less than or equal to 20 events. |
redacts |
string |
For redaction events, the ID of the event being redacted. |
room_id |
string |
Required: Room identifier. |
sender |
string |
Required: The ID of the user sending the event. |
signatures |
{string: Server Signatures} |
Required: Signatures for the PDU, following the algorithm specified in Signing Events. |
state_key |
string |
If this key is present, the event is a state event, and it will replace previous events
with the same type and state_key in the room state. |
type |
string |
Required: Event type |
unsigned |
UnsignedData |
Additional data added by the origin server but not covered by the signatures . |
Name | Type | Description |
---|---|---|
sha256 |
string |
Required: The event hash. |
Name | Type | Description |
---|---|---|
sha256 |
string |
Required: The hash. |
Name | Type | Description |
---|---|---|
age |
integer |
The number of milliseconds that have passed since this message was sent. |
Examples
{
"auth_events": [
"$af232176:example.org",
{
"sha256": "abase64encodedsha256hashshouldbe43byteslong"
}
],
"content": {
"key": "value"
},
"depth": 12,
"event_id": "$a4ecee13e2accdadf56c1025:example.com",
"hashes": {
"sha256": "thishashcoversallfieldsincasethisisredacted"
},
"origin": "example.com",
"origin_server_ts": 1404838188000,
"prev_events": [
"$af232176:example.org",
{
"sha256": "abase64encodedsha256hashshouldbe43byteslong"
}
],
"room_id": "!UcYsUzyxTGDxLBEvLy:example.org",
"sender": "@alice:example.com",
"signatures": {
"example.com": {
"ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
}
},
"type": "m.room.message",
"unsigned": {
"age": 4612
}
}
Deprecated event content schemas
Events sent into rooms of this version can have formats which are different from their normal schema. Those cases are documented here.
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
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:
{
"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 "
);
Authorization rules
The types of state events that affect authorization are:
sender
’s power level can also refer to
the default power level for users in the room.
The rules are as follows:
- If type is
m.room.create
:- If it has any
prev_events
, reject. - If the domain of the
room_id
does not match the domain of thesender
, reject. - If
content.room_version
is present and is not a recognised version, reject. - If
content
has nocreator
property, reject. - Otherwise, allow.
- If it has any
- Considering the event’s
auth_events
:- If there are duplicate entries for a given
type
andstate_key
pair, reject. - If there are entries whose
type
andstate_key
don’t match those specified by the auth events selection algorithm described in the server specification, reject. - If there are entries which were themselves rejected under the checks performed on receipt of a PDU, reject.
- If there is no
m.room.create
event among the entries, reject.
- If there are duplicate entries for a given
- If the
content
of them.room.create
event in the room state has the propertym.federate
set tofalse
, and thesender
domain of the event does not match thesender
domain of the create event, reject. - If type is
m.room.aliases
:- If event has no
state_key
, reject. - If sender’s domain doesn’t matches
state_key
, reject. - Otherwise, allow.
- If event has no
- If type is
m.room.member
:- If there is no
state_key
property, or nomembership
property incontent
, reject. - If
membership
isjoin
:- If the only previous event is an
m.room.create
and thestate_key
is the creator, allow. - If the
sender
does not matchstate_key
, reject. - If the
sender
is banned, reject. - If the
join_rule
isinvite
then allow if membership state isinvite
orjoin
. - If the
join_rule
ispublic
, allow. - Otherwise, reject.
- If the only previous event is an
- If
membership
isinvite
:- If
content
has athird_party_invite
property:- If target user is banned, reject.
- If
content.third_party_invite
does not have asigned
property, reject. - If
signed
does not havemxid
andtoken
properties, reject. - If
mxid
does not matchstate_key
, reject. - If there is no
m.room.third_party_invite
event in the current room state withstate_key
matchingtoken
, reject. - If
sender
does not matchsender
of them.room.third_party_invite
, reject. - If any signature in
signed
matches any public key in them.room.third_party_invite
event, allow. The public keys are incontent
ofm.room.third_party_invite
as:- A single public key in the
public_key
property. - A list of public keys in the
public_keys
property.
- A single public key in the
- Otherwise, reject.
- If the
sender
’s current membership state is notjoin
, reject. - If target user’s current membership state is
join
orban
, reject. - If the
sender
’s power level is greater than or equal to the invite level, allow. - Otherwise, reject.
- If
- If
membership
isleave
:- If the
sender
matchesstate_key
, allow if and only if that user’s current membership state isinvite
orjoin
. - If the
sender
’s current membership state is notjoin
, reject. - If the target user’s current membership state is
ban
, and thesender
’s power level is less than the ban level, reject. - 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 thesender
’s power level, allow. - Otherwise, reject.
- If the
- If
membership
isban
:- If the
sender
’s current membership state is notjoin
, reject. - 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 thesender
’s power level, allow. - Otherwise, reject.
- If the
- Otherwise, the membership is unknown. Reject.
- If there is no
- If the
sender
’s current membership state is notjoin
, reject. - If type is
m.room.third_party_invite
:- Allow if and only if
sender
’s current power level is greater than or equal to the invite level.
- Allow if and only if
- If the event type’s required power level is greater than the
sender
’s power level, reject. - If the event has a
state_key
that starts with an@
and does not match thesender
, reject. - If type is
m.room.power_levels
:- If the
users
property incontent
is not an object with keys that are valid user IDs with values that are integers (or a string that is an integer), reject. - If there is no previous
m.room.power_levels
event in the room, allow. - For the properties
users_default
,events_default
,state_default
,ban
,redact
,kick
,invite
check if they were added, changed or removed. For each found alteration:- If the current value is greater than the
sender
’s current power level, reject. - If the new value is greater than the
sender
’s current power level, reject.
- If the current value is greater than the
- For each entry being changed in, or removed from, the
events
property:- If the current value is greater than the
sender
’s current power level, reject.
- If the current value is greater than the
- For each entry being added to, or changed in, the
events
property:- If the new value is greater than the
sender
’s current power level, reject.
- If the new value is greater than the
- For each entry being changed in, or removed from, the
users
property, other than thesender
’s own entry:- If the current value is greater than or equal to the
sender
’s current power level, reject.
- If the current value is greater than or equal to the
- For each entry being added to, or changed in, the
users
property:- If the new value is greater than the
sender
’s current power level, reject.
- If the new value is greater than the
- Otherwise, allow.
- If the
- If type is
m.room.redaction
:- If the
sender
’s power level is greater than or equal to the redact level, allow. - If the domain of the
event_id
of the event being redacted is the same as the domain of theevent_id
of them.room.redaction
, allow. - Otherwise, reject.
- If the
- Otherwise, allow.
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.
State resolution
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, admins and moderators could lose their power level, and users who have been banned from the room may be able to rejoin. Other state events such 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.
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 event or a message event:
- If E is a message event, then S′(E) = S(E).
- If E is a state event, then S′(E) is S(E), except that its
entry corresponding to the
event_type
andstate_key
of E is replaced by theevent_id
of E.
The room state S(E) before E is the resolution of the set of
states {S′(E′), S′(E″), …} after the prev_events
{E′, E″, …}.
of E.
The resolution of a set of states is defined as follows. The resolved state is built up in a number of passes; here we use R to refer to the results of the resolution so far.
- Start by setting R to the union of the states to be resolved, excluding any conflicting events.
- First we resolve conflicts between
m.room.power_levels
events. If there is no conflict, this step is skipped, otherwise:- Assemble all the
m.room.power_levels
events from the states to be resolved into a list. - Sort the list by ascending
depth
then descendingsha1(event_id)
. - Add the first event in the list to R.
- For each subsequent event in the list, check that the event
would be allowed by the authorization rules for a room in state
R. If the event would be allowed, then update R with the
event and continue with the next event in the list. If it would
not be allowed, stop and continue below with
m.room.join_rules
events.
- Assemble all the
- Repeat the above process for conflicts between
m.room.join_rules
events. - Repeat the above process for conflicts between
m.room.member
events. - No other events affect the authorization rules, so for all other
conflicts, just pick the event with the highest depth and lowest
sha1(event_id)
that passes authentication in R and add it to R.
A conflict occurs between states where those states have different
event_ids
for the same (event_type, state_key)
. The events thus
affected are said to be conflicting events.
Canonical JSON
Servers MUST NOT strictly enforce the JSON format specified in the appendices for the reasons described there.