matrix-spec-proposals/drafts/flows_and_auth.rst

Failures
--------

A server may encouter an error when trying to process an event received from a
remote server. In these cases the server may send a `failure` to the remote.

A `failure` references both the event that it was trying to process and the
event that triggered the processing. For example, a failure may be emitted if
one of the parents of the received events was not authorized.

A failure also includes a `severity` field that indicates what action was taken
by the server. There are three valid values:

  * `Fatal`: The server failed to parse the event. The event is dropped by the
    server as well as all descendants.
  * `Error`: The server rejected the event, for example due to authorization.
    That event is dropped, but descendants may be accepted.
  * `Warn`: The server accepted all events, but believes the remote did
    something wrong. For example, references an event the local server believes
    is unauthorized.


Data Flows
----------

Invite
++++++

To invite a remote user to an existing room a server distributes an invitiation
event signed by the remote invitee's server (allowing other servers in the room
to be sure that the invitee's server had seen the invite.)

To get the remote server's signature on the event it is sent in a special
request to the remote server, which then responds with the signed invite (if it
accepted it as valid.) The remote server may respond with an error if the user
does not exist.

Join
++++

If a server is already in the room it can simply emit a join event for the user
joining.

If the server is not currently in the room it needs to join via a remote server
in the room, therefore to join a room a server must have have both the room id
and a list of remote servers that may be in the room.

To join via a remote server the local server first requests a valid join event
for the room from the remote server. The local then fills it out, signs it, and
then sends the final join event to the remote server for distribution. The
remore responds to this second request with the current state of the room at
the join request and the auth chain for that state.


Authorization
-------------

The authorization for an event depends solely on the current state at that
event. If a policy server is configured for the room, then the authorization
for the event is the signature of the policy server.

The state events that affect whether an event is authorized are called
`protocol events`, and are:

  * `m.room.create`
  * `m.room.power_levels`
  * `m.room.member`
  * `m.room.join_rules`

All events *must* list all the protocol events that grant them their
authorization. All origin servers *must* serve up on request the full graph of
protocol events for all events it has sent. The graph of protocol events is the
connected directed acyclic graph with events as nodes and the list of protocol
events their edges.


Join
++++

A user may join a room if:

  * The join rule is "public".
  * The join rule is "invite" and the user has been invited by a user that has
    already joined.
  * The user is in the `may_join` list.


Invite
++++++

A user may invite another user if the join rule is either "public" or "invite"
and the user has joined the room.


Creation
++++++++

A `m.room.create` must be the first event in the room.


Ban, Kick and Redaction
+++++++++++++++++++++++

To ban or kick another user in the room, or to redact an event, then the user
must have a power level of at least that specificied in the
`m.room.power_level` event for kick, ban and redactions.


Other Events
++++++++++++

A user may send an event if all the following hold true:

  * The user is in the room.
  * If the type of the event is listed in the `m.room.power_levels`, then the
    user must have at least that power level. Otherwise, the user must have a
    power level of at least `events_default` or `state_default`, depending on
    if the event is a message or state event respectively.


Unauthorized Events
-------------------

An unauthorized event should not be accepted into the event graph, i.e. new
events should not reference any unauthorized events. There are situations where
this can happen and so it is not considered an error to include an unauthorized
event in the event graph. It is an error for events to refer unauthorized
events in their `auth_events` section and will in turn be considered
unauthorized.

A server may choose to store only the redacted form of an unauthorized event if
it is included in the event graph.

A server may emit a warning to a remote server if it references an event it
considers unauthorized.


State and Authorization Querying
--------------------------------

A local server may become aware that it and a remote server's view of the
current state are inconsistent. The local server may then send its current
state to the remote, which responds with its view of the current state. Both
servers should then recompute the local state. If they are conforming
implementations then they will reach the same conclusions.