Added skeleton specification for a general feel of the layout.
Kegan Dougal
parent
f3f32addca
commit
64e927108b
|
|
@ -0,0 +1,648 @@
|
|||
Matrix Specification
|
||||
====================
|
||||
|
||||
TODO(Introduction) : Matthew
|
||||
- Similar to intro paragraph from README.
|
||||
- Explaining the overall mission, what this spec describes...
|
||||
- "What is Matrix?"
|
||||
|
||||
Architecture
|
||||
============
|
||||
|
||||
- Basic structure: What are clients/home servers and what are their
|
||||
responsibilities? What are events.
|
||||
|
||||
::
|
||||
|
||||
{ Matrix clients } { Matrix clients }
|
||||
^ | ^ |
|
||||
| events | | events |
|
||||
| V | V
|
||||
+------------------+ +------------------+
|
||||
| |---------( HTTP )---------->| |
|
||||
| Home Server | | Home Server |
|
||||
| |<--------( HTTP )-----------| |
|
||||
+------------------+ +------------------+
|
||||
|
||||
- How do identity servers fit in? 3PIDs? Users? Aliases
|
||||
- Pattern of the APIs (HTTP/JSON, REST + txns)
|
||||
- Standard error response format.
|
||||
- C-S Event stream
|
||||
|
||||
Rooms
|
||||
=====
|
||||
|
||||
A room is a conceptual place where users can send and receive messages. Rooms
|
||||
can be created, joined and left. Messages are sent to a room, and all
|
||||
participants in that room will receive the message. Rooms are uniquely
|
||||
identified via a room ID. There is exactly one room ID for each room.
|
||||
|
||||
- Aliases
|
||||
- Invite/join dance
|
||||
- State and non-state data (+extensibility)
|
||||
|
||||
TODO : Room permissions / config / power levels.
|
||||
|
||||
Messages
|
||||
========
|
||||
|
||||
This specification outlines several standard message types, all of which are
|
||||
prefixed with "m.".
|
||||
|
||||
- Namespacing?
|
||||
|
||||
State messages
|
||||
--------------
|
||||
- m.room.name
|
||||
- m.room.topic
|
||||
- m.room.member
|
||||
- m.room.config
|
||||
- m.room.invite_join
|
||||
|
||||
What are they, when are they used, what do they contain, how should they be used
|
||||
|
||||
Non-state messages
|
||||
------------------
|
||||
- m.room.message
|
||||
- m.room.message.feedback (and compressed format)
|
||||
|
||||
What are they, when are they used, what do they contain, how should they be used
|
||||
|
||||
m.room.message types
|
||||
--------------------
|
||||
- m.text
|
||||
- m.emote
|
||||
- m.audio
|
||||
- m.image
|
||||
- m.video
|
||||
- m.location
|
||||
|
||||
|
||||
Presence
|
||||
========
|
||||
|
||||
Each user has the concept of Presence information. This encodes a sense of the
|
||||
"availability" of that user, suitable for display on other user's clients.
|
||||
|
||||
The basic piece of presence information is an enumeration of a small set of
|
||||
state; such as "free to chat", "online", "busy", or "offline". The default state
|
||||
unless the user changes it is "online". Lower states suggest some amount of
|
||||
decreased availability from normal, which might have some client-side effect
|
||||
like muting notification sounds and suggests to other users not to bother them
|
||||
unless it is urgent. Equally, the "free to chat" state exists to let the user
|
||||
announce their general willingness to receive messages moreso than default.
|
||||
|
||||
Home servers should also allow a user to set their state as "hidden" - a state
|
||||
which behaves as offline, but allows the user to see the client state anyway and
|
||||
generally interact with client features such as reading message history or
|
||||
accessing contacts in the address book.
|
||||
|
||||
This basic state field applies to the user as a whole, regardless of how many
|
||||
client devices they have connected. The home server should synchronise this
|
||||
status choice among multiple devices to ensure the user gets a consistent
|
||||
experience.
|
||||
|
||||
Idle Time
|
||||
---------
|
||||
As well as the basic state field, the presence information can also show a sense
|
||||
of an "idle timer". This should be maintained individually by the user's
|
||||
clients, and the homeserver can take the highest reported time as that to
|
||||
report. Likely this should be presented in fairly coarse granularity; possibly
|
||||
being limited to letting the home server automatically switch from a "free to
|
||||
chat" or "online" mode into "idle".
|
||||
|
||||
When a user is offline, the Home Server can still report when the user was last
|
||||
seen online, again perhaps in a somewhat coarse manner.
|
||||
|
||||
Device Type
|
||||
-----------
|
||||
Client devices that may limit the user experience somewhat (such as "mobile"
|
||||
devices with limited ability to type on a real keyboard or read large amounts of
|
||||
text) should report this to the home server, as this is also useful information
|
||||
to report as "presence" if the user cannot be expected to provide a good typed
|
||||
response to messages.
|
||||
|
||||
- m.presence and enums (when should they be used)
|
||||
|
||||
Presence List
|
||||
-------------
|
||||
Each user's home server stores a "presence list" for that user. This stores a
|
||||
list of other user IDs the user has chosen to add to it (remembering any ACL
|
||||
Pointer if appropriate).
|
||||
|
||||
To be added to a contact list, the user being added must grant permission. Once
|
||||
granted, both user's HS(es) store this information, as it allows the user who
|
||||
has added the contact some more abilities; see below. Since such subscriptions
|
||||
are likely to be bidirectional, HSes may wish to automatically accept requests
|
||||
when a reverse subscription already exists.
|
||||
|
||||
As a convenience, presence lists should support the ability to collect users
|
||||
into groups, which could allow things like inviting the entire group to a new
|
||||
("ad-hoc") chat room, or easy interaction with the profile information ACL
|
||||
implementation of the HS.
|
||||
|
||||
Presence and Permissions
|
||||
------------------------
|
||||
For a viewing user to be allowed to see the presence information of a target
|
||||
user, either
|
||||
|
||||
* The target user has allowed the viewing user to add them to their presence
|
||||
list, or
|
||||
|
||||
* The two users share at least one room in common
|
||||
|
||||
In the latter case, this allows for clients to display some minimal sense of
|
||||
presence information in a user list for a room.
|
||||
|
||||
Home servers can also use the user's choice of presence state as a signal for
|
||||
how to handle new private one-to-one chat message requests. For example, it
|
||||
might decide:
|
||||
|
||||
- "free to chat": accept anything
|
||||
- "online": accept from anyone in my address book list
|
||||
- "busy": accept from anyone in this "important people" group in my address
|
||||
book list
|
||||
|
||||
Typing notifications
|
||||
====================
|
||||
|
||||
TODO : Leo
|
||||
|
||||
Voice over IP
|
||||
=============
|
||||
|
||||
TODO : Dave
|
||||
|
||||
Profiles
|
||||
========
|
||||
|
||||
Internally within Matrix users are referred to by their user ID, which is not a
|
||||
human-friendly string. Profiles grant users the ability to see human-readable
|
||||
names for other users that are in some way meaningful to them. Additionally,
|
||||
profiles can publish additional information, such as the user's age or location.
|
||||
|
||||
It is also conceivable that since we are attempting to provide a
|
||||
worldwide-applicable messaging system, that users may wish to present different
|
||||
subsets of information in their profile to different other people, from a
|
||||
privacy and permissions perspective.
|
||||
|
||||
A Profile consists of a display name, an avatar picture, and a set of other
|
||||
metadata fields that the user may wish to publish (email address, phone
|
||||
numbers, website URLs, etc...). This specification puts no requirements on the
|
||||
display name other than it being a valid Unicode string.
|
||||
|
||||
- Metadata extensibility
|
||||
- Bundled with which events? e.g. m.room.member
|
||||
|
||||
Registration and login
|
||||
======================
|
||||
|
||||
Clients must register with a home server in order to use Matrix. After
|
||||
registering, the client will be given an access token which must be used in ALL
|
||||
requests to that home server as a query parameter 'access_token'.
|
||||
|
||||
- TODO Kegan : Make registration like login
|
||||
- TODO Kegan : Allow alternative forms of login (>1 route)
|
||||
|
||||
If the client has already registered, they need to be able to login to their
|
||||
account. The home server may provide many different ways of logging in, such
|
||||
as user/password auth, login via a social network (OAuth), login by confirming
|
||||
a token sent to their email address, etc. This specification does not define how
|
||||
home servers should authorise their users who want to login to their existing
|
||||
accounts, but instead defines the standard interface which implementations
|
||||
should follow so that ANY client can login to ANY home server.
|
||||
|
||||
The login process breaks down into the following:
|
||||
1. Get login process info.
|
||||
2. Submit the login stage credentials.
|
||||
3. Get access token or be told the next stage in the login process and repeat
|
||||
step 2.
|
||||
|
||||
- What are types?
|
||||
|
||||
Matrix-defined login types
|
||||
--------------------------
|
||||
- m.login.password
|
||||
- m.login.oauth2
|
||||
- m.login.email.code
|
||||
- m.login.email.url
|
||||
|
||||
Password-based
|
||||
--------------
|
||||
Type: "m.login.password"
|
||||
LoginSubmission::
|
||||
|
||||
{
|
||||
"type": "m.login.password",
|
||||
"user": <user_id>,
|
||||
"password": <password>
|
||||
}
|
||||
|
||||
Example:
|
||||
Assume you are @bob:matrix.org and you wish to login on another mobile device.
|
||||
First, you GET /login which returns::
|
||||
|
||||
{
|
||||
"type": "m.login.password"
|
||||
}
|
||||
|
||||
Your client knows how to handle this, so your client prompts the user to enter
|
||||
their username and password. This is then submitted::
|
||||
|
||||
{
|
||||
"type": "m.login.password",
|
||||
"user": "@bob:matrix.org",
|
||||
"password": "monkey"
|
||||
}
|
||||
|
||||
The server checks this, finds it is valid, and returns::
|
||||
|
||||
{
|
||||
"access_token": "abcdef0123456789"
|
||||
}
|
||||
|
||||
The server may optionally return "user_id" to confirm or change the user's ID.
|
||||
This is particularly useful if the home server wishes to support localpart entry
|
||||
of usernames (e.g. "bob" rather than "@bob:matrix.org").
|
||||
|
||||
OAuth2-based
|
||||
------------
|
||||
Type: "m.login.oauth2"
|
||||
This is a multi-stage login.
|
||||
|
||||
LoginSubmission::
|
||||
|
||||
{
|
||||
"type": "m.login.oauth2",
|
||||
"user": <user_id>
|
||||
}
|
||||
|
||||
Returns::
|
||||
|
||||
{
|
||||
"uri": <Authorization Request uri OR service selection uri>
|
||||
}
|
||||
|
||||
The home server acts as a 'confidential' Client for the purposes of OAuth2.
|
||||
|
||||
If the uri is a "sevice selection uri", it is a simple page which prompts the
|
||||
user to choose which service to authorize with. On selection of a service, they
|
||||
link through to Authorization Request URIs. If there is only 1 service which the
|
||||
home server accepts when logging in, this indirection can be skipped and the
|
||||
"uri" key can be the Authorization Request URI.
|
||||
|
||||
The client visits the Authorization Request URI, which then shows the OAuth2
|
||||
Allow/Deny prompt. Hitting 'Allow' returns the redirect URI with the auth code.
|
||||
Home servers can choose any path for the redirect URI. The client should visit
|
||||
the redirect URI, which will then finish the OAuth2 login process, granting the
|
||||
home server an access token for the chosen service. When the home server gets
|
||||
this access token, it knows that the cilent has authed with the 3rd party, and
|
||||
so can return a LoginResult.
|
||||
|
||||
The OAuth redirect URI (with auth code) MUST return a LoginResult.
|
||||
|
||||
Example:
|
||||
Assume you are @bob:matrix.org and you wish to login on another mobile device.
|
||||
First, you GET /login which returns::
|
||||
|
||||
{
|
||||
"type": "m.login.oauth2"
|
||||
}
|
||||
|
||||
Your client knows how to handle this, so your client prompts the user to enter
|
||||
their username. This is then submitted::
|
||||
|
||||
{
|
||||
"type": "m.login.oauth2",
|
||||
"user": "@bob:matrix.org"
|
||||
}
|
||||
|
||||
The server only accepts auth from Google, so returns the Authorization Request
|
||||
URI for Google::
|
||||
|
||||
{
|
||||
"uri": "https://accounts.google.com/o/oauth2/auth?response_type=code&
|
||||
client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=photos"
|
||||
}
|
||||
|
||||
The client then visits this URI and authorizes the home server. The client then
|
||||
visits the REDIRECT_URI with the auth code= query parameter which returns::
|
||||
|
||||
{
|
||||
"access_token": "0123456789abcdef"
|
||||
}
|
||||
|
||||
Email-based (code)
|
||||
------------------
|
||||
Type: "m.login.email.code"
|
||||
This is a multi-stage login.
|
||||
|
||||
First LoginSubmission::
|
||||
|
||||
{
|
||||
"type": "m.login.email.code",
|
||||
"user": <user_id>
|
||||
"email": <email address>
|
||||
}
|
||||
|
||||
Returns::
|
||||
|
||||
{
|
||||
"type": m.login.email.code
|
||||
"session": <session id>
|
||||
}
|
||||
|
||||
The email contains a code which must be sent in the next LoginSubmission::
|
||||
|
||||
{
|
||||
"type": "m.login.email.code",
|
||||
"session": <session id>,
|
||||
"code": <code in email sent>
|
||||
}
|
||||
|
||||
Returns::
|
||||
|
||||
{
|
||||
"access_token": <access token>
|
||||
}
|
||||
|
||||
Email-based (url)
|
||||
-----------------
|
||||
Type: "m.login.email.url"
|
||||
This is a multi-stage login.
|
||||
|
||||
First LoginSubmission::
|
||||
|
||||
{
|
||||
"type": "m.login.email.url",
|
||||
"user": <user_id>
|
||||
"email": <email address>
|
||||
}
|
||||
|
||||
Returns::
|
||||
|
||||
{
|
||||
"session": <session id>
|
||||
}
|
||||
|
||||
The email contains a URL which must be clicked. After it has been clicked, the
|
||||
client should perform a request::
|
||||
|
||||
{
|
||||
"type": "m.login.email.code",
|
||||
"session": <session id>
|
||||
}
|
||||
|
||||
Returns::
|
||||
|
||||
{
|
||||
"access_token": <access token>
|
||||
}
|
||||
|
||||
Example:
|
||||
Assume you are @bob:matrix.org and you wish to login on another mobile device.
|
||||
First, you GET /login which returns::
|
||||
|
||||
{
|
||||
"type": "m.login.email.url"
|
||||
}
|
||||
|
||||
Your client knows how to handle this, so your client prompts the user to enter
|
||||
their email address. This is then submitted::
|
||||
|
||||
{
|
||||
"type": "m.login.email.url",
|
||||
"user": "@bob:matrix.org",
|
||||
"email": "bob@mydomain.com"
|
||||
}
|
||||
|
||||
The server confirms that bob@mydomain.com is linked to @bob:matrix.org, then
|
||||
sends an email to this address and returns::
|
||||
|
||||
{
|
||||
"session": "ewuigf7462"
|
||||
}
|
||||
|
||||
The client then starts polling the server with the following::
|
||||
|
||||
{
|
||||
"type": "m.login.email.url",
|
||||
"session": "ewuigf7462"
|
||||
}
|
||||
|
||||
(Alternatively, the server could send the device a push notification when the
|
||||
email has been validated). The email arrives and it contains a URL to click on.
|
||||
The user clicks on the which completes the login process with the server. The
|
||||
next time the client polls, it returns::
|
||||
|
||||
{
|
||||
"access_token": "abcdef0123456789"
|
||||
}
|
||||
|
||||
N-Factor auth
|
||||
-------------
|
||||
Multiple login stages can be combined with the "next" key in the LoginResult.
|
||||
|
||||
Example:
|
||||
A server demands an email.code then password auth before logging in. First, the
|
||||
client performs a GET /login which returns::
|
||||
|
||||
{
|
||||
"type": "m.login.email.code",
|
||||
"stages": ["m.login.email.code", "m.login.password"]
|
||||
}
|
||||
|
||||
The client performs the email login (See "Email-based (code)"), but instead of
|
||||
returning an access_token, it returns::
|
||||
|
||||
{
|
||||
"next": "m.login.password"
|
||||
}
|
||||
|
||||
The client then presents a user/password screen and the login continues until
|
||||
this is complete (See "Password-based"), which then returns the "access_token".
|
||||
|
||||
Fallback
|
||||
--------
|
||||
|
||||
If the client does NOT know how to handle the given type, they should::
|
||||
|
||||
GET /login/fallback
|
||||
|
||||
This MUST return an HTML page which can perform the entire login process.
|
||||
|
||||
Identity
|
||||
========
|
||||
|
||||
TODO : Dave
|
||||
- 3PIDs and identity server, functions
|
||||
|
||||
Federation
|
||||
==========
|
||||
|
||||
Federation is the term used to describe how to communicate between Matrix home
|
||||
servers. Federation is a mechanism by which two home servers can exchange
|
||||
Matrix event messages, both as a real-time push of current events, and as a
|
||||
historic fetching mechanism to synchronise past history for clients to view. It
|
||||
uses HTTP connections between each pair of servers involved as the underlying
|
||||
transport. Messages are exchanged between servers in real-time by active pushing
|
||||
from each server's HTTP client into the server of the other. Queries to fetch
|
||||
historic data for the purpose of back-filling scrollback buffers and the like
|
||||
can also be performed.
|
||||
|
||||
There are three main kinds of communication that occur between home servers:
|
||||
|
||||
* Queries
|
||||
These are single request/response interactions between a given pair of
|
||||
servers, initiated by one side sending an HTTP request to obtain some
|
||||
information, and responded by the other. They are not persisted and contain
|
||||
no long-term significant history. They simply request a snapshot state at the
|
||||
instant the query is made.
|
||||
|
||||
* EDUs - Ephemeral Data Units
|
||||
These are notifications of events that are pushed from one home server to
|
||||
another. They are not persisted and contain no long-term significant history,
|
||||
nor does the receiving home server have to reply to them.
|
||||
|
||||
* PDUs - Persisted Data Units
|
||||
These are notifications of events that are broadcast from one home server to
|
||||
any others that are interested in the same "context" (namely, a Room ID).
|
||||
They are persisted to long-term storage and form the record of history for
|
||||
that context.
|
||||
|
||||
Where Queries are presented directly across the HTTP connection as GET requests
|
||||
to specific URLs, EDUs and PDUs are further wrapped in an envelope called a
|
||||
Transaction, which is transferred from the origin to the destination home server
|
||||
using a PUT request.
|
||||
|
||||
|
||||
Transactions and EDUs/PDUs
|
||||
--------------------------
|
||||
The transfer of EDUs and PDUs between home servers is performed by an exchange
|
||||
of Transaction messages, which are encoded as JSON objects with a dict as the
|
||||
top-level element, passed over an HTTP PUT request. A Transaction is meaningful
|
||||
only to the pair of home servers that exchanged it; they are not globally-
|
||||
meaningful.
|
||||
|
||||
Each transaction has an opaque ID and timestamp (UNIX epoch time in
|
||||
milliseconds) generated by its origin server, an origin and destination server
|
||||
name, a list of "previous IDs", and a list of PDUs - the actual message payload
|
||||
that the Transaction carries.
|
||||
|
||||
{"transaction_id":"916d630ea616342b42e98a3be0b74113",
|
||||
"ts":1404835423000,
|
||||
"origin":"red",
|
||||
"destination":"blue",
|
||||
"prev_ids":["e1da392e61898be4d2009b9fecce5325"],
|
||||
"pdus":[...],
|
||||
"edus":[...]}
|
||||
|
||||
The "previous IDs" field will contain a list of previous transaction IDs that
|
||||
the origin server has sent to this destination. Its purpose is to act as a
|
||||
sequence checking mechanism - the destination server can check whether it has
|
||||
successfully received that Transaction, or ask for a retransmission if not.
|
||||
|
||||
The "pdus" field of a transaction is a list, containing zero or more PDUs.[*]
|
||||
Each PDU is itself a dict containing a number of keys, the exact details of
|
||||
which will vary depending on the type of PDU. Similarly, the "edus" field is
|
||||
another list containing the EDUs. This key may be entirely absent if there are
|
||||
no EDUs to transfer.
|
||||
|
||||
(* Normally the PDU list will be non-empty, but the server should cope with
|
||||
receiving an "empty" transaction, as this is useful for informing peers of other
|
||||
transaction IDs they should be aware of. This effectively acts as a push
|
||||
mechanism to encourage peers to continue to replicate content.)
|
||||
|
||||
All PDUs have an ID, a context, a declaration of their type, a list of other PDU
|
||||
IDs that have been seen recently on that context (regardless of which origin
|
||||
sent them), and a nested content field containing the actual event content.
|
||||
|
||||
[[TODO(paul): Update this structure so that 'pdu_id' is a two-element
|
||||
[origin,ref] pair like the prev_pdus are]]
|
||||
|
||||
{"pdu_id":"a4ecee13e2accdadf56c1025af232176",
|
||||
"context":"#example.green",
|
||||
"origin":"green",
|
||||
"ts":1404838188000,
|
||||
"pdu_type":"m.text",
|
||||
"prev_pdus":[["blue","99d16afbc857975916f1d73e49e52b65"]],
|
||||
"content":...
|
||||
"is_state":false}
|
||||
|
||||
In contrast to the transaction layer, it is important to note that the prev_pdus
|
||||
field of a PDU refers to PDUs that any origin server has sent, rather than
|
||||
previous IDs that this origin has sent. This list may refer to other PDUs sent
|
||||
by the same origin as the current one, or other origins.
|
||||
|
||||
Because of the distributed nature of participants in a Matrix conversation, it
|
||||
is impossible to establish a globally-consistent total ordering on the events.
|
||||
However, by annotating each outbound PDU at its origin with IDs of other PDUs it
|
||||
has received, a partial ordering can be constructed allowing causallity
|
||||
relationships to be preserved. A client can then display these messages to the
|
||||
end-user in some order consistent with their content and ensure that no message
|
||||
that is semantically in reply of an earlier one is ever displayed before it.
|
||||
|
||||
PDUs fall into two main categories: those that deliver Events, and those that
|
||||
synchronise State. For PDUs that relate to State synchronisation, additional
|
||||
keys exist to support this:
|
||||
|
||||
{...,
|
||||
"is_state":true,
|
||||
"state_key":TODO
|
||||
"power_level":TODO
|
||||
"prev_state_id":TODO
|
||||
"prev_state_origin":TODO}
|
||||
|
||||
[[TODO(paul): At this point we should probably have a long description of how
|
||||
State management works, with descriptions of clobbering rules, power levels, etc
|
||||
etc... But some of that detail is rather up-in-the-air, on the whiteboard, and
|
||||
so on. This part needs refining. And writing in its own document as the details
|
||||
relate to the server/system as a whole, not specifically to server-server
|
||||
federation.]]
|
||||
|
||||
EDUs, by comparison to PDUs, do not have an ID, a context, or a list of
|
||||
"previous" IDs. The only mandatory fields for these are the type, origin and
|
||||
destination home server names, and the actual nested content.
|
||||
|
||||
{"edu_type":"m.presence",
|
||||
"origin":"blue",
|
||||
"destination":"orange",
|
||||
"content":...}
|
||||
|
||||
Backfilling
|
||||
-----------
|
||||
- What it is, when is it used, how is it done
|
||||
|
||||
SRV Records
|
||||
-----------
|
||||
- Why it is needed
|
||||
|
||||
Security
|
||||
========
|
||||
- rate limiting
|
||||
- crypto (s-s auth)
|
||||
- E2E
|
||||
- Lawful intercept + Key Escrow
|
||||
|
||||
TODO Mark
|
||||
|
||||
Policy Servers
|
||||
==============
|
||||
TODO
|
||||
|
||||
Content repository
|
||||
==================
|
||||
- thumbnail paths
|
||||
|
||||
Address book repository
|
||||
=======================
|
||||
- format
|
||||
|
||||
|
||||
Glossary
|
||||
========
|
||||
- domain specific words/acronyms with definitions
|
||||
|
||||
User ID:
|
||||
An opaque ID which identifies an end-user, which consists of some opaque
|
||||
localpart combined with the domain name of their home server.
|
||||
Loading…
Reference in New Issue