archive
/
matrix-spec
mirror of https://github.com/matrix-org/matrix-spec
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Consistently spell homeserver as homeserver

Browse Source
pull/977/head
Daniel Wagner-Hall 9 years ago
parent 138c8f88be
commit 2f3a00fe34
39 changed files with 235 additions and 235 deletions
Show Stats Download Patch File Download Diff File

6
api/client-server/administrative_contact.yaml
Unescape Escape View File

@ -25,7 +25,7 @@ paths:
This API endpoint uses the User-Interactive Authentication API. This API endpoint uses the User-Interactive Authentication API.
An access token should be submitted to this endpoint if the client has An access token should be submitted to this endpoint if the client has
an active session. an active session.
The Home Server may change the flows available depending on whether a The homeserver may change the flows available depending on whether a
valid access token is provided. valid access token is provided.
security: security:
- accessToken: [] - accessToken: []
@ -64,7 +64,7 @@ paths:
This is *not* the same as the list of third party identifiers bound to This is *not* the same as the list of third party identifiers bound to
the user's Matrix ID in Identity Servers. the user's Matrix ID in Identity Servers.
Identifiers in this list may be used by the Home Server as, for example, Identifiers in this list may be used by the homeserver as, for example,
identifiers that it will accept to reset the user's account password. identifiers that it will accept to reset the user's account password.
security: security:
- accessToken: [] - accessToken: []
@ -126,7 +126,7 @@ paths:
bind: bind:
type: boolean type: boolean
description: |- description: |-
Whether the home server should also bind this third party Whether the homeserver should also bind this third party
identifier to the account's Matrix ID with the passed identity identifier to the account's Matrix ID with the passed identity
server. Default: ``false``. server. Default: ``false``.
x-example: true x-example: true

2
api/client-server/create_room.yaml
Unescape Escape View File

@ -57,7 +57,7 @@ paths:
description: |- description: |-
The desired room alias **local part**. If this is included, a The desired room alias **local part**. If this is included, a
room alias will be created and mapped to the newly created room alias will be created and mapped to the newly created
room. The alias will belong on the *same* home server which room. The alias will belong on the *same* homeserver which
created the room. For example, if this was set to "foo" and created the room. For example, if this was set to "foo" and
sent to the homeserver "example.com" the complete room alias sent to the homeserver "example.com" the complete room alias
would be ``#foo:example.com``. would be ``#foo:example.com``.

2
api/client-server/inviting.yaml
Unescape Escape View File

@ -38,7 +38,7 @@ paths:
Only users currently in a particular room can invite other users to Only users currently in a particular room can invite other users to
join that room. join that room.
If the user was invited to the room, the home server will append a If the user was invited to the room, the homeserver will append a
``m.room.member`` event to the room. ``m.room.member`` event to the room.
.. _third party invites section: `invite-by-third-party-id-endpoint`_ .. _third party invites section: `invite-by-third-party-id-endpoint`_

2
api/client-server/login.yaml
Unescape Escape View File

@ -81,7 +81,7 @@ paths:
(optional) A ``refresh_token`` may be exchanged for a new ``access_token`` using the /tokenrefresh API endpoint. (optional) A ``refresh_token`` may be exchanged for a new ``access_token`` using the /tokenrefresh API endpoint.
home_server: home_server:
type: string type: string
description: The hostname of the Home Server on which the account has been registered. description: The hostname of the homeserver on which the account has been registered.
400: 400:
description: |- description: |-
Part of the request was invalid. For example, the login type may not be recognised. Part of the request was invalid. For example, the login type may not be recognised.

2
api/client-server/pusher.yaml
Unescape Escape View File

@ -114,7 +114,7 @@ paths:
description: |- description: |-
If true, the homeserver should add another pusher with the If true, the homeserver should add another pusher with the
given pushkey and App ID in addition to any others with given pushkey and App ID in addition to any others with
different user IDs. Otherwise, the Home Server must remove any different user IDs. Otherwise, the homeserver must remove any
other pushers with the same App ID and pushkey for different other pushers with the same App ID and pushkey for different
users. The default is ``false``. users. The default is ``false``.
required: ['profile_tag', 'kind', 'app_id', 'app_display_name', required: ['profile_tag', 'kind', 'app_id', 'app_display_name',

4
api/client-server/registration.yaml
Unescape Escape View File

@ -94,7 +94,7 @@ paths:
(optional) A ``refresh_token`` may be exchanged for a new ``access_token`` using the /tokenrefresh API endpoint. (optional) A ``refresh_token`` may be exchanged for a new ``access_token`` using the /tokenrefresh API endpoint.
home_server: home_server:
type: string type: string
description: The hostname of the Home Server on which the account has been registered. description: The hostname of the homeserver on which the account has been registered.
400: 400:
description: |- description: |-
Part of the request was invalid. This may include one of the following error codes: Part of the request was invalid. This may include one of the following error codes:
@ -107,7 +107,7 @@ paths:
including after authentication if the requested user ID was registered including after authentication if the requested user ID was registered
whilst the client was performing authentication. whilst the client was performing authentication.
Home Servers MUST perform the relevant checks and return these codes before Homeservers MUST perform the relevant checks and return these codes before
performing `User-Interactive Authentication`_, although they may also return performing `User-Interactive Authentication`_, although they may also return
them after authentication is completed if, for example, the requested user ID them after authentication is completed if, for example, the requested user ID
was registered whilst the client was performing authentication. was registered whilst the client was performing authentication.

4
api/client-server/third_party_membership.yaml
Unescape Escape View File

@ -39,7 +39,7 @@ paths:
join that room. join that room.
If the identity server did know the Matrix user identifier for the If the identity server did know the Matrix user identifier for the
third party identifier, the home server will append a ``m.room.member`` third party identifier, the homeserver will append a ``m.room.member``
event to the room. event to the room.
If the identity server does not know a Matrix user identifier for the If the identity server does not know a Matrix user identifier for the
@ -62,7 +62,7 @@ paths:
- The matrix user ID who invited them to the room - The matrix user ID who invited them to the room
If a token is requested from the identity server, the home server will If a token is requested from the identity server, the homeserver will
append a ``m.room.third_party_invite`` event to the room. append a ``m.room.third_party_invite`` event to the room.
.. _joining rooms section: `invite-by-user-id-endpoint`_ .. _joining rooms section: `invite-by-user-id-endpoint`_

48
attic/v1_registration_login.rst
Unescape Escape View File

@ -1,17 +1,17 @@
Registration and Login Registration and Login
---------------------- ----------------------
Clients must register with a home server in order to use Matrix. After Clients must register with a homeserver in order to use Matrix. After
registering, the client will be given an access token which must be used in ALL 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'. requests to that homeserver as a query parameter 'access_token'.
If the client has already registered, they need to be able to login to their 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 account. The homeserver may provide many different ways of logging in, such as
user/password auth, login via a social network (OAuth2), login by confirming a user/password auth, login via a social network (OAuth2), login by confirming a
token sent to their email address, etc. This specification does not define how 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 homeservers should authorise their users who want to login to their existing
accounts, but instead defines the standard interface which implementations accounts, but instead defines the standard interface which implementations
should follow so that ANY client can login to ANY home server. Clients login should follow so that ANY client can login to ANY homeserver. Clients login
using the |login|_ API. Clients register using the |register|_ API. using the |login|_ API. Clients register using the |register|_ API.
Registration follows the same general procedure as login, but the path requests Registration follows the same general procedure as login, but the path requests
are sent to and the details contained in them are different. are sent to and the details contained in them are different.
@ -26,7 +26,7 @@ In order to determine up-front what the server's requirements are, the client
can request from the server a complete description of all of its acceptable can request from the server a complete description of all of its acceptable
flows of the registration or login process. It can then inspect the list of flows of the registration or login process. It can then inspect the list of
returned flows looking for one for which it believes it can complete all of the returned flows looking for one for which it believes it can complete all of the
required stages, and perform it. As each home server may have different ways of required stages, and perform it. As each homeserver may have different ways of
logging in, the client needs to know how they should login. All distinct login logging in, the client needs to know how they should login. All distinct login
stages MUST have a corresponding ``type``. A ``type`` is a namespaced string stages MUST have a corresponding ``type``. A ``type`` is a namespaced string
which details the mechanism for logging in. which details the mechanism for logging in.
@ -64,12 +64,12 @@ ID and a new access token MUST be returned::
"access_token": "abcdef0123456789" "access_token": "abcdef0123456789"
} }
The ``user_id`` key is particularly useful if the home server wishes to support The ``user_id`` key is particularly useful if the homeserver wishes to support
localpart entry of usernames (e.g. "user" rather than "@user:matrix.org"), as localpart entry of usernames (e.g. "user" rather than "@user:matrix.org"), as
the client may not be able to determine its ``user_id`` in this case. the client may not be able to determine its ``user_id`` in this case.
If the flow has multiple stages to it, the home server may wish to create a If the flow has multiple stages to it, the homeserver may wish to create a
session to store context between requests. If a home server responds with a session to store context between requests. If a homeserver responds with a
``session`` key to a request, clients MUST submit it in subsequent requests ``session`` key to a request, clients MUST submit it in subsequent requests
until the flow is completed:: until the flow is completed::
@ -99,7 +99,7 @@ To respond to this type, reply with::
"password": "<password>" "password": "<password>"
} }
The home server MUST respond with either new credentials, the next stage of the The homeserver MUST respond with either new credentials, the next stage of the
login process, or a standard error response. login process, or a standard error response.
Captcha-based Captcha-based
@ -123,7 +123,7 @@ To respond to this type, reply with::
Recaptcha.get_challenge(); Recaptcha.get_challenge();
Recaptcha.get_response(); Recaptcha.get_response();
The home server MUST respond with either new credentials, the next stage of the The homeserver MUST respond with either new credentials, the next stage of the
login process, or a standard error response. login process, or a standard error response.
OAuth2-based OAuth2-based
@ -146,24 +146,24 @@ The server MUST respond with::
"uri": <Authorization Request URI OR service selection URI> "uri": <Authorization Request URI OR service selection URI>
} }
The home server acts as a 'confidential' client for the purposes of OAuth2. If The homeserver acts as a 'confidential' client for the purposes of OAuth2. If
the uri is a ``sevice selection URI``, it MUST point to a webpage which prompts the uri is a ``sevice selection URI``, it MUST point to a webpage which prompts
the user to choose which service to authorize with. On selection of a service, the user to choose which service to authorize with. On selection of a service,
this MUST link through to an ``Authorization Request URI``. If there is only 1 this MUST link through to an ``Authorization Request URI``. If there is only 1
service which the home server accepts when logging in, this indirection can be service which the homeserver accepts when logging in, this indirection can be
skipped and the "uri" key can be the ``Authorization Request URI``. skipped and the "uri" key can be the ``Authorization Request URI``.
The client then visits the ``Authorization Request URI``, which then shows the The client then visits the ``Authorization Request URI``, which then shows the
OAuth2 Allow/Deny prompt. Hitting 'Allow' returns the ``redirect URI`` with 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 auth code. Homeservers can choose any path for the ``redirect URI``. The
client should visit the ``redirect URI``, which will then finish the OAuth2 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. login process, granting the homeserver an access token for the chosen service.
When the home server gets this access token, it verifies that the cilent has When the homeserver gets this access token, it verifies that the cilent has
authorised with the 3rd party, and can now complete the login. The OAuth2 authorised with the 3rd party, and can now complete the login. The OAuth2
``redirect URI`` (with auth code) MUST respond with either new credentials, the ``redirect URI`` (with auth code) MUST respond with either new credentials, the
next stage of the login process, or a standard error response. next stage of the login process, or a standard error response.
For example, if a home server accepts OAuth2 from Google, it would return the For example, if a homeserver accepts OAuth2 from Google, it would return the
Authorization Request URI for Google:: Authorization Request URI for Google::
{ {
@ -171,7 +171,7 @@ Authorization Request URI for Google::
client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=photos" client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=photos"
} }
The client then visits this URI and authorizes the home server. The client then The client then visits this URI and authorizes the homeserver. The client then
visits the REDIRECT_URI with the auth code= query parameter which returns:: visits the REDIRECT_URI with the auth code= query parameter which returns::
{ {
@ -195,7 +195,7 @@ To respond to this type, reply with::
"email": "<email address>" "email": "<email address>"
} }
After validating the email address, the home server MUST send an email After validating the email address, the homeserver MUST send an email
containing an authentication code and return:: containing an authentication code and return::
{ {
@ -212,7 +212,7 @@ code::
"code": "<code in email sent>" "code": "<code in email sent>"
} }
The home server MUST respond to this with either new credentials, the next The homeserver MUST respond to this with either new credentials, the next
stage of the login process, or a standard error response. stage of the login process, or a standard error response.
Email-based (url) Email-based (url)
@ -231,7 +231,7 @@ To respond to this type, reply with::
"email": "<email address>" "email": "<email address>"
} }
After validating the email address, the home server MUST send an email After validating the email address, the homeserver MUST send an email
containing an authentication URL and return:: containing an authentication URL and return::
{ {
@ -247,7 +247,7 @@ client should perform another request::
"session": "<session id>" "session": "<session id>"
} }
The home server MUST respond to this with either new credentials, the next The homeserver MUST respond to this with either new credentials, the next
stage of the login process, or a standard error response. stage of the login process, or a standard error response.
A common client implementation will be to periodically poll until the link is A common client implementation will be to periodically poll until the link is
@ -264,7 +264,7 @@ Email-based (identity server)
Prior to submitting this, the client should authenticate with an identity Prior to submitting this, the client should authenticate with an identity
server. After authenticating, the session information should be submitted to server. After authenticating, the session information should be submitted to
the home server. the homeserver.
To respond to this type, reply with:: To respond to this type, reply with::
@ -293,7 +293,7 @@ of a previous login stage::
"next": "<next login type>" "next": "<next login type>"
} }
If a home server implements N-factor authentication, it MUST respond with all If a homeserver implements N-factor authentication, it MUST respond with all
``stages`` when initially queried for their login requirements:: ``stages`` when initially queried for their login requirements::
{ {

6
drafts/ancient_federated_versioning_design_notes.rst
Unescape Escape View File

@ -1,11 +1,11 @@
Versioning is, like, hard for backfilling backwards because of the number of Home Servers involved. Versioning is, like, hard for backfilling backwards because of the number of homeservers involved.
The way we solve this is by doing versioning as an acyclic directed graph of PDUs. For backfilling purposes, this is done on a per context basis. The way we solve this is by doing versioning as an acyclic directed graph of PDUs. For backfilling purposes, this is done on a per context basis.
When we send a PDU we include all PDUs that have been received for that context that hasn't been subsequently listed in a later PDU. The trivial case is a simple list of PDUs, e.g. A <- B <- C. However, if two servers send out a PDU at the same to, both B and C would point at A - a later PDU would then list both B and C. When we send a PDU we include all PDUs that have been received for that context that hasn't been subsequently listed in a later PDU. The trivial case is a simple list of PDUs, e.g. A <- B <- C. However, if two servers send out a PDU at the same to, both B and C would point at A - a later PDU would then list both B and C.
Problems with opaque version strings: Problems with opaque version strings:
- How do you do clustering without mandating that a cluster can only have one transaction in flight to a given remote home server at a time. - How do you do clustering without mandating that a cluster can only have one transaction in flight to a given remote homeserver at a time.
If you have multiple transactions sent at once, then you might drop one transaction, receive another with a version that is later than the dropped transaction and which point ARGH WE LOST A TRANSACTION. If you have multiple transactions sent at once, then you might drop one transaction, receive another with a version that is later than the dropped transaction and which point ARGH WE LOST A TRANSACTION.
- How do you do backfilling? A version string defines a point in a stream w.r.t. a single home server, not a point in the context. - How do you do backfilling? A version string defines a point in a stream w.r.t. a single homeserver, not a point in the context.
We only need to store the ends of the directed graph, we DO NOT need to do the whole one table of nodes and one of edges. We only need to store the ends of the directed graph, we DO NOT need to do the whole one table of nodes and one of edges.

42
drafts/as-http-api.rst
Unescape Escape View File

@ -13,9 +13,9 @@ Application Services HTTP API
.. sectnum:: .. sectnum::
Application Service -> Home Server Application Service -> Homeserver
---------------------------------- ----------------------------------
This contains home server APIs which are used by the application service. This contains homeserver APIs which are used by the application service.
Registration API ``[Draft]`` Registration API ``[Draft]``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -34,7 +34,7 @@ Output:
Side effects: Side effects:
- The HS will start delivering events to the URL base specified if this 200s. - The HS will start delivering events to the URL base specified if this 200s.
API called when: API called when:
- The application service wants to register with a brand new home server. - The application service wants to register with a brand new homeserver.
Notes: Notes:
- An application service can state whether they should be the only ones who - An application service can state whether they should be the only ones who
can manage a specified namespace. This is referred to as an "exclusive" can manage a specified namespace. This is referred to as an "exclusive"
@ -100,7 +100,7 @@ Notes:
Unregister API ``[Draft]`` Unregister API ``[Draft]``
~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~
This API unregisters a previously registered AS from the home server. This API unregisters a previously registered AS from the homeserver.
Inputs: Inputs:
- AS token - AS token
@ -122,9 +122,9 @@ API called when:
} }
Home Server -> Application Service Homeserver -> Application Service
---------------------------------- ----------------------------------
This contains application service APIs which are used by the home server. This contains application service APIs which are used by the homeserver.
User Query ``[Draft]`` User Query ``[Draft]``
~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~
@ -152,9 +152,9 @@ Notes:
- This is deemed more flexible than alternative methods (e.g. returning a JSON blob with the - This is deemed more flexible than alternative methods (e.g. returning a JSON blob with the
user's display name and get the HS to provision the user). user's display name and get the HS to provision the user).
Retry notes: Retry notes:
- The home server cannot respond to the client's request until the response to - The homeserver cannot respond to the client's request until the response to
this API is obtained from the AS. this API is obtained from the AS.
- Recommended that home servers try a few times then time out, returning a - Recommended that homeservers try a few times then time out, returning a
408 Request Timeout to the client. 408 Request Timeout to the client.
:: ::
@ -199,9 +199,9 @@ Notes:
style JSON blob and get the HS to provision the room). It also means that the AS knows style JSON blob and get the HS to provision the room). It also means that the AS knows
the room ID -> alias mapping. the room ID -> alias mapping.
Retry notes: Retry notes:
- The home server cannot respond to the client's request until the response to - The homeserver cannot respond to the client's request until the response to
this API is obtained from the AS. this API is obtained from the AS.
- Recommended that home servers try a few times then time out, returning a - Recommended that homeservers try a few times then time out, returning a
408 Request Timeout to the client. 408 Request Timeout to the client.
:: ::
@ -236,13 +236,13 @@ Data flows:
:: ::
Typical Typical
HS ---> AS : Home server sends events with transaction ID T. HS ---> AS : Homeserver sends events with transaction ID T.
<--- : AS sends back 200 OK. <--- : AS sends back 200 OK.
AS ACK Lost AS ACK Lost
HS ---> AS : Home server sends events with transaction ID T. HS ---> AS : Homeserver sends events with transaction ID T.
<-/- : AS 200 OK is lost. <-/- : AS 200 OK is lost.
HS ---> AS : Home server retries with the same transaction ID of T. HS ---> AS : Homeserver retries with the same transaction ID of T.
<--- : AS sends back 200 OK. If the AS had processed these events <--- : AS sends back 200 OK. If the AS had processed these events
already, it can NO-OP this request (and it knows if it is the same already, it can NO-OP this request (and it knows if it is the same
events based on the transacton ID). events based on the transacton ID).
@ -253,15 +253,15 @@ Retry notes:
- Since ASes by definition cannot alter the traffic being passed to it (unlike - Since ASes by definition cannot alter the traffic being passed to it (unlike
say, a Policy Server), these requests can be done in parallel to general HS say, a Policy Server), these requests can be done in parallel to general HS
processing; the HS doesn't need to block whilst doing this. processing; the HS doesn't need to block whilst doing this.
- Home servers should use exponential backoff as their retry algorithm. - Homeservers should use exponential backoff as their retry algorithm.
- Home servers MUST NOT alter (e.g. add more) events they were going to - Homeservers MUST NOT alter (e.g. add more) events they were going to
send within that transaction ID on retries, as the AS may have already send within that transaction ID on retries, as the AS may have already
processed the events. processed the events.
Ordering notes: Ordering notes:
- The events sent to the AS should be linearised, as they are from the event - The events sent to the AS should be linearised, as they are from the event
stream. stream.
- The home server will need to maintain a queue of transactions to send to - The homeserver will need to maintain a queue of transactions to send to
the AS. the AS.
:: ::
@ -336,7 +336,7 @@ Notes:
Server admin style permissions Server admin style permissions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The home server needs to give the application service *full control* over its The homeserver needs to give the application service *full control* over its
namespace, both for users and for room aliases. This means that the AS should namespace, both for users and for room aliases. This means that the AS should
be able to create/edit/delete any room alias in its namespace, as well as be able to create/edit/delete any room alias in its namespace, as well as
create/delete any user in its namespace. No additional API changes need to be create/delete any user in its namespace. No additional API changes need to be
@ -451,15 +451,15 @@ Examples
IRC IRC
~~~ ~~~
Pre-conditions: Pre-conditions:
- Server admin stores the AS token "T_a" on the home server. - Server admin stores the AS token "T_a" on the homeserver.
- Home server has a token "T_h". - Homeserver has a token "T_h".
- Home server has the domain "hsdomain.com" - Homeserver has the domain "hsdomain.com"
1. Application service registration 1. Application service registration
:: ::
AS -> HS: Registers itself with the home server AS -> HS: Registers itself with the homeserver
POST /register POST /register
{ {
url: "https://someapp.com/matrix", url: "https://someapp.com/matrix",

6
drafts/erikj_federation.rst
Unescape Escape View File

@ -237,7 +237,7 @@ Domain specific string
``room_id`` ``room_id``
A domain specific string with prefix ``!`` that is static across all events A domain specific string with prefix ``!`` that is static across all events
in a graph and uniquely identifies it. The ``domain`` should be that of the in a graph and uniquely identifies it. The ``domain`` should be that of the
home server that created the room (i.e., the server that generated the homeserver that created the room (i.e., the server that generated the
first ``m.room.create`` event). first ``m.room.create`` event).
``sender`` ``sender``
@ -246,7 +246,7 @@ Domain specific string
User Id User Id
A domain specific string with prefix ``@`` representing a user account. The A domain specific string with prefix ``@`` representing a user account. The
``domain`` is the home server of the user and is the server used to contact ``domain`` is the homeserver of the user and is the server used to contact
the user. the user.
Joining a room Joining a room
@ -280,7 +280,7 @@ can then process the join event itself.
Inviting a user Inviting a user
--------------- ---------------
To invite a remote user to a room we need their home server to sign the invite To invite a remote user to a room we need their homeserver to sign the invite
event. This is done by sending the event to the remote server, which then signs event. This is done by sending the event to the remote server, which then signs
the event, before distributing the invite to other servers. the event, before distributing the invite to other servers.

54
drafts/general_api.rst
Unescape Escape View File

@ -61,7 +61,7 @@ This version will change the path prefix for HTTP:
- Version 2: ``/_matrix/client/v2`` - Version 2: ``/_matrix/client/v2``
Note the lack of the ``api`` segment. This is for consistency between other Note the lack of the ``api`` segment. This is for consistency between other
home server path prefixes. homeserver path prefixes.
Terminology: Terminology:
- ``Chunk token`` : An opaque string which can be used to return another chunk - ``Chunk token`` : An opaque string which can be used to return another chunk
@ -169,16 +169,16 @@ Outputs:
``content`` key. Deleted message events are ``m.room.redaction`` events. ``content`` key. Deleted message events are ``m.room.redaction`` events.
- New position in the stream. (chunk token) - New position in the stream. (chunk token)
State Events Ordering Notes: State Events Ordering Notes:
- Home servers may receive state events over federation that are superceded by - Homeservers may receive state events over federation that are superceded by
state events previously sent to the client. The home server *cannot* send state events previously sent to the client. The homeserver *cannot* send
these events to the client else they would end up erroneously clobbering the these events to the client else they would end up erroneously clobbering the
superceding state event. superceding state event.
- As a result, the home server reserves the right to omit sending state events - As a result, the homeserver reserves the right to omit sending state events
which are known to be superceded already. which are known to be superceded already.
- This may result in missed *state* events. However, the state of the room will - This may result in missed *state* events. However, the state of the room will
always be eventually consistent. always be eventually consistent.
Message Events Ordering Notes: Message Events Ordering Notes:
- Home servers may receive message events over federation that happened a long - Homeservers may receive message events over federation that happened a long
time ago. The client may or may not be interested in these message events. time ago. The client may or may not be interested in these message events.
- For clients which do not store scrollback for a room (they discard events - For clients which do not store scrollback for a room (they discard events
after processing them), this is not a problem as they only care about the after processing them), this is not a problem as they only care about the
@ -191,11 +191,11 @@ Message Events Ordering Notes:
- The event, when it comes down the stream, will indicate which event it comes - The event, when it comes down the stream, will indicate which event it comes
after. after.
Rejected events: Rejected events:
- A home server may find out via federation that it should not have accepted - A homeserver may find out via federation that it should not have accepted
an event (e.g. to send a message/state event in a room). For example, it may an event (e.g. to send a message/state event in a room). For example, it may
send an event to another home server and receive an auth event stating send an event to another homeserver and receive an auth event stating
that the event should not have been sent. that the event should not have been sent.
- If this happens, the home server will send a ``m.room.redaction`` for the - If this happens, the homeserver will send a ``m.room.redaction`` for the
event in question. This will be a local server event (not shared with other event in question. This will be a local server event (not shared with other
servers). servers).
- If the event was a state event, it will synthesise a new state event to - If the event was a state event, it will synthesise a new state event to
@ -206,7 +206,7 @@ Unknown rooms:
- You could receive events for rooms you are unaware of (e.g. you didn't do an - You could receive events for rooms you are unaware of (e.g. you didn't do an
initial sync, or your HS lost its database and is told from another HS that initial sync, or your HS lost its database and is told from another HS that
they are in this room). How do you handle this? they are in this room). How do you handle this?
- The simplest option would be to redo the initial sync with a filter on the - The simplest option would be to redo the initial sync with a filter on the
room ID you're unaware of. This would retrieve the room state so you can room ID you're unaware of. This would retrieve the room state so you can
display the room. display the room.
What data flows does it address: What data flows does it address:
@ -291,7 +291,7 @@ Scrollback API ``[Draft]``
but as a purely informational display thing it would be nice. but as a purely informational display thing it would be nice.
Additional Inputs: Additional Inputs:
- flag to say if the home server should do a backfill over federation - flag to say if the homeserver should do a backfill over federation
Additional Outputs: Additional Outputs:
- whether there are more events on the local HS / over federation. - whether there are more events on the local HS / over federation.
What data flows does it address: What data flows does it address:
@ -313,7 +313,7 @@ Additional Outputs:
Room Alias API ``[Draft]`` Room Alias API ``[Draft]``
-------------------------- --------------------------
This provides mechanisms for creating and removing room aliases for a room on a This provides mechanisms for creating and removing room aliases for a room on a
home server. Typically, any user in a room can make an alias for that room. The homeserver. Typically, any user in a room can make an alias for that room. The
alias creator (or anyone in the room?) can delete that alias. Server admins can alias creator (or anyone in the room?) can delete that alias. Server admins can
also delete any alias on their server. also delete any alias on their server.
@ -323,7 +323,7 @@ Inputs:
- Room Alias - Room Alias
Output: Output:
- Room ID - Room ID
- List of home servers to join via. - List of homeservers to join via.
Mapping a room to an alias: Mapping a room to an alias:
@ -334,7 +334,7 @@ Inputs:
Output: Output:
- Room alias - Room alias
Notes: Notes:
- The home server may add restrictions e.g. the user must be in the room. - The homeserver may add restrictions e.g. the user must be in the room.
Deleting a mapping: Deleting a mapping:
@ -347,11 +347,11 @@ Output:
Published room list API ``[Draft]`` Published room list API ``[Draft]``
----------------------------------- -----------------------------------
This provides mechanisms for searching for published rooms on a home server. This provides mechanisms for searching for published rooms on a homeserver.
Inputs: Inputs:
- Search text (e.g. room alias/name/topic to search on) - Search text (e.g. room alias/name/topic to search on)
- Home server to search on (this may just be the URL hit for HTTP) - Homeserver to search on (this may just be the URL hit for HTTP)
- Any existing pagination token, can be missing if this is the first hit. - Any existing pagination token, can be missing if this is the first hit.
- Limit for pagination - Limit for pagination
Output: Output:
@ -378,7 +378,7 @@ Notes:
User Profile API ``[Draft]`` User Profile API ``[Draft]``
---------------------------- ----------------------------
Every user on a home server has a profile. This profile is effectively a Every user on a homeserver has a profile. This profile is effectively a
key-value store scoped to a user ID. It can include an ``avatar_url``, key-value store scoped to a user ID. It can include an ``avatar_url``,
``displayname`` and other metadata. Updates to a profile should propagate to ``displayname`` and other metadata. Updates to a profile should propagate to
other interested users. other interested users.
@ -435,7 +435,7 @@ This had a number of problems associated with it:
flicker. flicker.
- Name/avatar changes created more ``m.room.member`` events which meant - Name/avatar changes created more ``m.room.member`` events which meant
they needed to be included in the auth chains for federation. This they needed to be included in the auth chains for federation. This
created long auth chains which is suboptimal since home servers need created long auth chains which is suboptimal since homeservers need
to store the auth chains forever. to store the auth chains forever.
These problems can be resolved by creating an ``m.room.member.profile`` These problems can be resolved by creating an ``m.room.member.profile``
@ -448,7 +448,7 @@ However, this introduces its own set of problems, namely flicker. The
client would receive the ``m.room.member`` event first, followed by client would receive the ``m.room.member`` event first, followed by
the ``m.room.member.profile`` event, which could cause a flicker. In the ``m.room.member.profile`` event, which could cause a flicker. In
addition, federation may not send both events in a single transaction, addition, federation may not send both events in a single transaction,
resulting in missing information on the receiving home server. resulting in missing information on the receiving homeserver.
For federation, these problems can be resolved by sending the For federation, these problems can be resolved by sending the
``m.room.member`` event as they are in v1 (with ``displayname`` and ``m.room.member`` event as they are in v1 (with ``displayname`` and
@ -457,7 +457,7 @@ they cannot be in the ``unsigned`` part of the event. The receiving home
server will then extract these keys and create a server-generated server will then extract these keys and create a server-generated
``m.room.member.profile`` event. To avoid confusion with duplicate ``m.room.member.profile`` event. To avoid confusion with duplicate
information, the ``avatar_url`` and ``displayname`` keys should be information, the ``avatar_url`` and ``displayname`` keys should be
removed from the ``m.room.member`` event by the receiving home server. removed from the ``m.room.member`` event by the receiving homeserver.
When a client requests these events (either from the event stream When a client requests these events (either from the event stream
or from an initial sync), the server will send the generated or from an initial sync), the server will send the generated
``m.room.member.profile`` event under the ``unsigned.profile`` key of the ``m.room.member.profile`` event under the ``unsigned.profile`` key of the
@ -840,17 +840,17 @@ information per device to all other users just redirects the union problem to
the client, which will commonly be presenting this information as an icon the client, which will commonly be presenting this information as an icon
alongside the user. alongside the user.
When a client hits the event stream, the home server can treat the user as When a client hits the event stream, the homeserver can treat the user as
"online". This behaviour should be able to be overridden to avoid flicker "online". This behaviour should be able to be overridden to avoid flicker
during connection losses when the client is appear offline (e.g. device is during connection losses when the client is appear offline (e.g. device is
appear offline > goes into a tunnel > server times out > device regains appear offline > goes into a tunnel > server times out > device regains
connection and hits the event stream forcing the device online before the connection and hits the event stream forcing the device online before the
"appear offline" state can be set). When the client has not hit the event "appear offline" state can be set). When the client has not hit the event
stream for a certain period of time, the home server can treat the user as stream for a certain period of time, the homeserver can treat the user as
"offline". The user can also set a global *per-user* appear offline flag. "offline". The user can also set a global *per-user* appear offline flag.
The user should also be able to set their presence state via a direct API, The user should also be able to set their presence state via a direct API,
without having to hit the event stream. The home server will set a timer when without having to hit the event stream. The homeserver will set a timer when
the connection ends, after which it will set that device to offline. the connection ends, after which it will set that device to offline.
As the idle flag and online state is determined per device, there needs to be a As the idle flag and online state is determined per device, there needs to be a
@ -970,12 +970,12 @@ the hashes the same is the best as that means clients do not need to request
the capabilities for the given hash. the capabilities for the given hash.
On first signup, the client will attempt to send the hash and be most likely On first signup, the client will attempt to send the hash and be most likely
refused by the home server as it does not know the full capability set for that refused by the homeserver as it does not know the full capability set for that
hash. The client will then have to upload the full capability set to the home hash. The client will then have to upload the full capability set to the home
server. The client will then be able to send the hash as normal. server. The client will then be able to send the hash as normal.
When a client receives a hash, the client will either recognise the hash or When a client receives a hash, the client will either recognise the hash or
will have to request the capability set from their home server: will have to request the capability set from their homeserver:
Inputs: Inputs:
- Hash - Hash
@ -1070,7 +1070,7 @@ Main use cases for ``updates``:
- Call signalling (child events are ICE candidates, answer to the offer, and - Call signalling (child events are ICE candidates, answer to the offer, and
termination) termination)
- *Local* Delivery/Read receipts : "Local" means they are not shared with other - *Local* Delivery/Read receipts : "Local" means they are not shared with other
users on the same home server or via federation but *are* shared between users on the same homeserver or via federation but *are* shared between
clients for the same user; useful for push notifications, read count markers, clients for the same user; useful for push notifications, read count markers,
etc. This is done to avoid the ``n^2`` problem for sending receipts, where etc. This is done to avoid the ``n^2`` problem for sending receipts, where
the vast majority of traffic tends towards sending more receipts. the vast majority of traffic tends towards sending more receipts.
@ -1168,11 +1168,11 @@ Events (breaking changes; event version 2) ``[Draft]``
when dealing with custom event types. E.g. ``_custom.event`` would allow when dealing with custom event types. E.g. ``_custom.event`` would allow
anything in the state key, ``_@custom.event`` would only allow user IDs in anything in the state key, ``_@custom.event`` would only allow user IDs in
the state key, etc. the state key, etc.
- s/user_id/sender/g given that home servers can send events, not just users. - s/user_id/sender/g given that homeservers can send events, not just users.
Server-generated events ``[Draft]`` Server-generated events ``[Draft]``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Home servers may want to send events to their local clients or to other home Homeservers may want to send events to their local clients or to other home
servers e.g. for server status notifications. servers e.g. for server status notifications.
These events look like regular events but have a server domain name as the These events look like regular events but have a server domain name as the

14
drafts/human-id-rules.rst
Unescape Escape View File

@ -13,9 +13,9 @@ phishing/spoofing of IDs, commonly known as a homograph attack.
Web browers encountered this problem when International Domain Names were Web browers encountered this problem when International Domain Names were
introduced. A variety of checks were put in place in order to protect users. If introduced. A variety of checks were put in place in order to protect users. If
an address failed the check, the raw punycode would be displayed to an address failed the check, the raw punycode would be displayed to
disambiguate the address. Similar checks are performed by home servers in disambiguate the address. Similar checks are performed by homeservers in
Matrix. However, Matrix does not use punycode representations, and so does not Matrix. However, Matrix does not use punycode representations, and so does not
show raw punycode on a failed check. Instead, home servers must outright reject show raw punycode on a failed check. Instead, homeservers must outright reject
these misleading IDs. these misleading IDs.
Types of human-readable IDs Types of human-readable IDs
@ -48,12 +48,12 @@ Checks
Rejecting Rejecting
--------- ---------
- Home servers MUST reject room aliases which do not pass the check, both on - Homeservers MUST reject room aliases which do not pass the check, both on
GETs and PUTs. GETs and PUTs.
- Home servers MUST reject user ID localparts which do not pass the check, both - Homeservers MUST reject user ID localparts which do not pass the check, both
on creation and on events. on creation and on events.
- Any home server whose domain does not pass this check, MUST use their punycode - Any homeserver whose domain does not pass this check, MUST use their punycode
domain name instead of the IDN, to prevent other home servers rejecting you. domain name instead of the IDN, to prevent other homeservers rejecting you.
- Error code is ``M_FAILED_HUMAN_ID_CHECK``. (generic enough for both failing - Error code is ``M_FAILED_HUMAN_ID_CHECK``. (generic enough for both failing
due to homograph attacks, and failing due to including ``:`` s, etc) due to homograph attacks, and failing due to including ``:`` s, etc)
- Error message MAY go into further information about which characters were - Error message MAY go into further information about which characters were
@ -74,7 +74,7 @@ Other considerations
- High security: Outright rejection of the ID at the point of creation / - High security: Outright rejection of the ID at the point of creation /
receiving event. Point of creation rejection is preferable to avoid the ID receiving event. Point of creation rejection is preferable to avoid the ID
entering the system in the first place. However, malicious HSes can just entering the system in the first place. However, malicious HSes can just
allow the ID. Hence, other home servers must reject them if they see them in allow the ID. Hence, other homeservers must reject them if they see them in
events. Client never sees the problem ID, provided the HS is correctly events. Client never sees the problem ID, provided the HS is correctly
implemented. implemented.
- High security decided; client doesn't need to worry about it, no additional - High security decided; client doesn't need to worry about it, no additional

12
drafts/model/presence.rst
Unescape Escape View File

@ -5,14 +5,14 @@ A simple implementation of presence messaging has the ability to cause a large
amount of Internet traffic relating to presence updates. In order to minimise amount of Internet traffic relating to presence updates. In order to minimise
the impact of such a feature, the following observations can be made: the impact of such a feature, the following observations can be made:
* There is no point in a Home Server polling status for peers in a user's * There is no point in a homeserver polling status for peers in a user's
presence list if the user has no clients connected that care about it. presence list if the user has no clients connected that care about it.
* It is highly likely that most presence subscriptions will be symmetric - a * It is highly likely that most presence subscriptions will be symmetric - a
given user watching another is likely to in turn be watched by that user. given user watching another is likely to in turn be watched by that user.
* It is likely that most subscription pairings will be between users who share * It is likely that most subscription pairings will be between users who share
at least one Room in common, and so their Home Servers are actively at least one Room in common, and so their homeservers are actively
exchanging message PDUs or transactions relating to that Room. exchanging message PDUs or transactions relating to that Room.
* Presence update messages do not need realtime guarantees. It is acceptable to * Presence update messages do not need realtime guarantees. It is acceptable to
@ -25,7 +25,7 @@ promise to send them when required. Rather than actively polling for the
current state all the time, HSes can rely on their relative stability to only current state all the time, HSes can rely on their relative stability to only
push updates when required. push updates when required.
A Home Server should not rely on the longterm validity of this presence A homeserver should not rely on the longterm validity of this presence
information, however, as this would not cover such cases as a user's server information, however, as this would not cover such cases as a user's server
crashing and thus failing to inform their peers that users it used to host are crashing and thus failing to inform their peers that users it used to host are
no longer available online. Therefore, each promise of future updates should no longer available online. Therefore, each promise of future updates should
@ -33,7 +33,7 @@ carry with a timeout value (whether explicit in the message, or implicit as some
defined default in the protocol), after which the receiving HS should consider defined default in the protocol), after which the receiving HS should consider
the information potentially stale and request it again. the information potentially stale and request it again.
However, because of the likelihood that two home servers are exchanging messages However, because of the likelihood that two homeservers are exchanging messages
relating to chat traffic in a room common to both of them, the ongoing receipt relating to chat traffic in a room common to both of them, the ongoing receipt
of these messages can be taken by each server as an implicit notification that of these messages can be taken by each server as an implicit notification that
the sending server is still up and running, and therefore that no status changes the sending server is still up and running, and therefore that no status changes
@ -98,7 +98,7 @@ The data model presented here puts the following requirements on the APIs:
Client-Server Client-Server
------------- -------------
Requests that a client can make to its Home Server Requests that a client can make to its homeserver
* get/set current presence state * get/set current presence state
Basic enumeration + ability to set a custom piece of text Basic enumeration + ability to set a custom piece of text
@ -128,7 +128,7 @@ Requests that a client can make to its Home Server
Server-Server Server-Server
------------- -------------
Requests that Home Servers make to others Requests that homeservers make to others
* request permission to add a user to presence list * request permission to add a user to presence list

16
drafts/model/profiles.rst
Unescape Escape View File

@ -9,7 +9,7 @@ Overview
======== ========
Internally within Synapse users are referred to by an opaque ID, which consists Internally within Synapse users are referred to by an opaque ID, which consists
of some opaque localpart combined with the domain name of their home server. of some opaque localpart combined with the domain name of their homeserver.
Obviously this does not yield a very nice user experience; users would like to Obviously this does not yield a very nice user experience; users would like to
see readable names for other users that are in some way meaningful to them. see readable names for other users that are in some way meaningful to them.
Additionally, users like to be able to publish "profile" details to inform other Additionally, users like to be able to publish "profile" details to inform other
@ -59,7 +59,7 @@ servers should be accounted for here.]]
Visibility Permissions Visibility Permissions
====================== ======================
A home server implementation could offer the ability to set permissions on A homeserver implementation could offer the ability to set permissions on
limited visibility of those fields. When another user requests access to the limited visibility of those fields. When another user requests access to the
target user's profile, their own identity should form part of that request. The target user's profile, their own identity should form part of that request. The
HS implementation can then decide which fields to make available to the HS implementation can then decide which fields to make available to the
@ -130,12 +130,12 @@ namespace to allocate names into.
It would also be nice from a user experience perspective if the profile that a It would also be nice from a user experience perspective if the profile that a
given name links to can also declare that name as part of its metadata. given name links to can also declare that name as part of its metadata.
Furthermore as a security and consistency perspective it would be nice if each Furthermore as a security and consistency perspective it would be nice if each
end (the directory server and the user's home server) check the validity of the end (the directory server and the user's homeserver) check the validity of the
mapping in some way. This needs investigation from a security perspective to mapping in some way. This needs investigation from a security perspective to
ensure against spoofing. ensure against spoofing.
One such model may be that the user starts by declaring their intent to use a One such model may be that the user starts by declaring their intent to use a
given user name link to their home server, which then contacts the directory given user name link to their homeserver, which then contacts the directory
service. At some point later (maybe immediately for "public open FCFS servers", service. At some point later (maybe immediately for "public open FCFS servers",
maybe after some kind of human intervention for verification) the DS decides to maybe after some kind of human intervention for verification) the DS decides to
honour this link, and includes it in its served output. It should also tell the honour this link, and includes it in its served output. It should also tell the
@ -170,7 +170,7 @@ balancing choice on behalf of the user who would choose, or not, to make use of
such a feature to publish their information. such a feature to publish their information.
Additionally, unless some form of strong end-to-end user-based encryption is Additionally, unless some form of strong end-to-end user-based encryption is
used, a user of ACLs for information privacy has to trust other home servers not used, a user of ACLs for information privacy has to trust other homeservers not
to lie about the identify of the user requesting access to the Profile. to lie about the identify of the user requesting access to the Profile.
@ -182,7 +182,7 @@ The data model presented here puts the following requirements on the APIs:
Client-Server Client-Server
------------- -------------
Requests that a client can make to its Home Server Requests that a client can make to its homeserver
* get/set my Display Name * get/set my Display Name
This should return/take a simple "text/plain" field This should return/take a simple "text/plain" field
@ -207,7 +207,7 @@ TODO(paul): At some later stage we should consider the API for:
Server-Server Server-Server
------------- -------------
Requests that Home Servers make to others Requests that homeservers make to others
* get a user's Display Name / Avatar * get a user's Display Name / Avatar
@ -221,7 +221,7 @@ Requests that Home Servers make to others
Room Event PDU Types Room Event PDU Types
-------------------- --------------------
Events that are pushed from Home Servers to other Home Servers or clients. Events that are pushed from homeservers to other homeservers or clients.
* user Display Name change * user Display Name change

12
drafts/model/room-join-workflow.rst
Unescape Escape View File

@ -8,7 +8,7 @@ Discovery
========= =========
To join a room, a user has to discover the room by some mechanism in order to To join a room, a user has to discover the room by some mechanism in order to
obtain the (opaque) Room ID and a candidate list of likely home servers that obtain the (opaque) Room ID and a candidate list of likely homeservers that
contain it. contain it.
Sending an Invitation Sending an Invitation
@ -21,7 +21,7 @@ The inviter's HS sets the membership status of the invitee to "invited" in the
"m.members" state key by sending a state update PDU. The HS then broadcasts this "m.members" state key by sending a state update PDU. The HS then broadcasts this
PDU among the existing members in the usual way. An invitation message is also PDU among the existing members in the usual way. An invitation message is also
sent to the invited user, containing the Room ID and the PDU ID of this sent to the invited user, containing the Room ID and the PDU ID of this
invitation state change and potentially a list of some other home servers to use invitation state change and potentially a list of some other homeservers to use
to accept the invite. The user's client can then choose to display it in some to accept the invite. The user's client can then choose to display it in some
way to alert the user. way to alert the user.
@ -34,7 +34,7 @@ Directory Service
Alternatively, the user may discover the channel via a directory service; either Alternatively, the user may discover the channel via a directory service; either
by performing a name lookup, or some kind of browse or search acitivty. However by performing a name lookup, or some kind of browse or search acitivty. However
this is performed, the end result is that the user's home server requests the this is performed, the end result is that the user's homeserver requests the
Room ID and candidate list from the directory service. Room ID and candidate list from the directory service.
[[TODO(paul): At present, no API has been designed or described for this [[TODO(paul): At present, no API has been designed or described for this
@ -44,14 +44,14 @@ directory service]]
Joining Joining
======= =======
Once the ID and home servers are obtained, the user can then actually join the Once the ID and homeservers are obtained, the user can then actually join the
room. room.
Accepting an Invite Accepting an Invite
------------------- -------------------
If a user has received and accepted an invitation to join a room, the invitee's If a user has received and accepted an invitation to join a room, the invitee's
home server can now send an invite acceptance message to a chosen candidate homeserver can now send an invite acceptance message to a chosen candidate
server from the list given in the invitation, citing also the PDU ID of the server from the list given in the invitation, citing also the PDU ID of the
invitation as "proof" of their invite. (This is required as due to late message invitation as "proof" of their invite. (This is required as due to late message
propagation it could be the case that the acceptance is received before the propagation it could be the case that the acceptance is received before the
@ -85,7 +85,7 @@ can instead post a "knock" message, which informs other members of the room that
the would-be joiner wishes to become a member and sets their membership value to the would-be joiner wishes to become a member and sets their membership value to
"knocked". If any of them wish to accept this, they can then send an invitation "knocked". If any of them wish to accept this, they can then send an invitation
in the usual way described above. Knowing that the user has already knocked and in the usual way described above. Knowing that the user has already knocked and
expressed an interest in joining, the invited user's home server should expressed an interest in joining, the invited user's homeserver should
immediately accept that invitation on the user's behalf, and go on to join the immediately accept that invitation on the user's behalf, and go on to join the
room in the usual way. room in the usual way.

20
drafts/model/rooms.rst
Unescape Escape View File

@ -18,19 +18,19 @@ users, and other management and miscellaneous metadata), and a message history.
Room Identity and Naming Room Identity and Naming
======================== ========================
Rooms can be arbitrarily created by any user on any home server; at which point Rooms can be arbitrarily created by any user on any homeserver; at which point
the home server will sign the message that creates the channel, and the the homeserver will sign the message that creates the channel, and the
fingerprint of this signature becomes the strong persistent identify of the fingerprint of this signature becomes the strong persistent identify of the
room. This now identifies the room to any home server in the network regardless room. This now identifies the room to any homeserver in the network regardless
of its original origin. This allows the identify of the room to outlive any of its original origin. This allows the identify of the room to outlive any
particular server. Subject to appropriate permissions [to be discussed later], particular server. Subject to appropriate permissions [to be discussed later],
any current member of a room can invite others to join it, can post messages any current member of a room can invite others to join it, can post messages
that become part of its history, and can change the persistent state of the room that become part of its history, and can change the persistent state of the room
(including its current set of permissions). (including its current set of permissions).
Home servers can provide a directory service, allowing a lookup from a Homeservers can provide a directory service, allowing a lookup from a
convenient human-readable form of room label to a room ID. This mapping is convenient human-readable form of room label to a room ID. This mapping is
scoped to the particular home server domain and so simply represents that server scoped to the particular homeserver domain and so simply represents that server
administrator's opinion of what room should take that label; it does not have to administrator's opinion of what room should take that label; it does not have to
be globally replicated and does not form part of the stored state of that room. be globally replicated and does not form part of the stored state of that room.
@ -156,7 +156,7 @@ m.public_history
to be a member of the room. to be a member of the room.
m.archive_servers m.archive_servers
For "public" rooms with public history, gives a list of home servers that For "public" rooms with public history, gives a list of homeservers that
should be included in message distribution to the room, even if no users on should be included in message distribution to the room, even if no users on
that server are present. These ensure that a public room can still persist that server are present. These ensure that a public room can still persist
even if no users are currently members of it. This list should be consulted by even if no users are currently members of it. This list should be consulted by
@ -179,7 +179,7 @@ m.topic
Room Creation Templates Room Creation Templates
======================= =======================
A client (or maybe home server?) could offer a few templates for the creation of A client (or maybe homeserver?) could offer a few templates for the creation of
new rooms. For example, for a simple private one-to-one chat the channel could new rooms. For example, for a simple private one-to-one chat the channel could
assign the creator a power-level of 1, requiring a level of 1 to invite, and assign the creator a power-level of 1, requiring a level of 1 to invite, and
needing an invite before members can join. An invite is then sent to the other needing an invite before members can join. An invite is then sent to the other
@ -215,7 +215,7 @@ permissions to allow this direct messaging.
Between any given pair of user IDs that wish to exchange private messages, there Between any given pair of user IDs that wish to exchange private messages, there
will exist a single shared Room, created lazily by either side. These rooms will will exist a single shared Room, created lazily by either side. These rooms will
need a certain amount of special handling in both home servers and display on need a certain amount of special handling in both homeservers and display on
clients, but as much as possible should be treated by the lower layers of code clients, but as much as possible should be treated by the lower layers of code
the same as other rooms. the same as other rooms.
@ -226,7 +226,7 @@ clients should display these in a special way too as the room name is not
important; instead it should distinguish them on the Display Name of the other important; instead it should distinguish them on the Display Name of the other
party. party.
Home Servers will need a client-API option to request setting up a new user-user Homeservers will need a client-API option to request setting up a new user-user
chat room, which will then need special handling within the server. It will chat room, which will then need special handling within the server. It will
create a new room with the following create a new room with the following
@ -260,7 +260,7 @@ history with each other simultaneously create a room and invite the other to it.
This is called a "glare" situation. There are two possible ideas for how to This is called a "glare" situation. There are two possible ideas for how to
resolve this: resolve this:
* Each Home Server should persist the mapping of (user ID pair) to room ID, so * Each homeserver should persist the mapping of (user ID pair) to room ID, so
that duplicate requests can be suppressed. On receipt of a room creation that duplicate requests can be suppressed. On receipt of a room creation
request that the HS thinks there already exists a room for, the invitation to request that the HS thinks there already exists a room for, the invitation to
join can be rejected if: join can be rejected if:

2
drafts/model/third-party-id.rst
Unescape Escape View File

@ -66,7 +66,7 @@ Privacy
A User may publish the association between their phone number and Matrix User ID A User may publish the association between their phone number and Matrix User ID
on the Identity Server without publishing the number in their Profile hosted on on the Identity Server without publishing the number in their Profile hosted on
their Home Server. their homeserver.
Identity Servers should refrain from publishing reverse mappings and should Identity Servers should refrain from publishing reverse mappings and should
take steps, such as rate limiting, to prevent attackers enumerating the space of take steps, such as rate limiting, to prevent attackers enumerating the space of

2
scripts/generate-http-docs.sh
Unescape Escape View File

@ -24,7 +24,7 @@ cat >tmp/http_apis <<EOF
Matrix Client-Server API Reference Matrix Client-Server API Reference
================================== ==================================
This contains the client-server API for the reference implementation of the home server. This contains the client-server API for the reference implementation of the homeserver.
EOF EOF

14
specification/application_service_api.rst
Unescape Escape View File

@ -89,7 +89,7 @@ traffic to the AS is:
identify the application service. The homeserver MUST enforce this. identify the application service. The homeserver MUST enforce this.
Home Server -> Application Service API Homeserver -> Application Service API
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Pushing events Pushing events
@ -101,13 +101,13 @@ events. Each list of events includes a transaction ID, which works as follows:
:: ::
Typical Typical
HS ---> AS : Home server sends events with transaction ID T. HS ---> AS : Homeserver sends events with transaction ID T.
<--- : AS sends back 200 OK. <--- : AS sends back 200 OK.
AS ACK Lost AS ACK Lost
HS ---> AS : Home server sends events with transaction ID T. HS ---> AS : Homeserver sends events with transaction ID T.
<-/- : AS 200 OK is lost. <-/- : AS 200 OK is lost.
HS ---> AS : Home server retries with the same transaction ID of T. HS ---> AS : Homeserver retries with the same transaction ID of T.
<--- : AS sends back 200 OK. If the AS had processed these events <--- : AS sends back 200 OK. If the AS had processed these events
already, it can NO-OP this request (and it knows if it is the same already, it can NO-OP this request (and it knows if it is the same
events based on the transaction ID). events based on the transaction ID).
@ -145,7 +145,7 @@ this request (e.g. to join a room alias).
HTTP APIs HTTP APIs
+++++++++ +++++++++
This contains application service APIs which are used by the home server. All This contains application service APIs which are used by the homeserver. All
application services MUST implement these APIs. These APIs are defined below. application services MUST implement these APIs. These APIs are defined below.
{{application_service_http_api}} {{application_service_http_api}}
@ -158,7 +158,7 @@ Client-Server v2 API Extensions
Application services can utilise a more powerful version of the Application services can utilise a more powerful version of the
client-server API by identifying itself as an application service to the client-server API by identifying itself as an application service to the
home server. homeserver.
Identity assertion Identity assertion
++++++++++++++++++ ++++++++++++++++++
@ -212,7 +212,7 @@ Server admin style permissions
.. _sect:asapi-permissions: .. _sect:asapi-permissions:
The home server needs to give the application service *full control* over its The homeserver needs to give the application service *full control* over its
namespace, both for users and for room aliases. This means that the AS should namespace, both for users and for room aliases. This means that the AS should
be able to create/edit/delete any room alias in its namespace, as well as be able to create/edit/delete any room alias in its namespace, as well as
create/delete any user in its namespace. No additional API changes need to be create/delete any user in its namespace. No additional API changes need to be

56
specification/client_server_api.rst
Unescape Escape View File

@ -147,12 +147,12 @@ User-Interactive Authentication API
This section refers to API Version 2. This section refers to API Version 2.
Some API endpoints such as ``login`` or ``register`` require authentication that Some API endpoints such as ``login`` or ``register`` require authentication that
interacts with the user. The home server may provide many different ways of interacts with the user. The homeserver may provide many different ways of
authenticating, such as user/password auth, login via a social network (OAuth2), authenticating, such as user/password auth, login via a social network (OAuth2),
login by confirming a token sent to their email address, etc. This specification login by confirming a token sent to their email address, etc. This specification
does not define how home servers should authorise their users but instead does not define how homeservers should authorise their users but instead
defines the standard interface which implementations should follow so that ANY defines the standard interface which implementations should follow so that ANY
client can login to ANY home server. client can login to ANY homeserver.
The process takes the form of one or more stages, where at each stage the client The process takes the form of one or more stages, where at each stage the client
submits a set of data for a given stage type and awaits a response from the submits a set of data for a given stage type and awaits a response from the
@ -168,9 +168,9 @@ more than one stage to implement n-factor auth. When all stages are complete,
authentication is complete and the API call succeeds. To establish what flows a authentication is complete and the API call succeeds. To establish what flows a
server supports for an endpoint, a client sends the request with no server supports for an endpoint, a client sends the request with no
authentication. A request to an endpoint that uses User-Interactive authentication. A request to an endpoint that uses User-Interactive
Authentication never succeeds without auth. Home Servers may allow requests that Authentication never succeeds without auth. Homeservers may allow requests that
don't require auth by offering a stage with only the ``m.login.dummy`` auth don't require auth by offering a stage with only the ``m.login.dummy`` auth
type. The home server returns a response with HTTP status 401 and a JSON object type. The homeserver returns a response with HTTP status 401 and a JSON object
as follows:: as follows::
{ {
@ -208,7 +208,7 @@ does this by resubmitting the same request with the the addition of an 'auth'
key in the object that it submits. This dictionary contains a ``type`` key whose key in the object that it submits. This dictionary contains a ``type`` key whose
value is the name of the stage type that the client is attempting to complete. value is the name of the stage type that the client is attempting to complete.
It must also contains a ``session`` key with the value of the session key given It must also contains a ``session`` key with the value of the session key given
by the home server, if one was given. It also contains other keys dependent on by the homeserver, if one was given. It also contains other keys dependent on
the stage type being attempted. For example, if the client is attempting to the stage type being attempted. For example, if the client is attempting to
complete login type ``example.type.foo``, it might submit something like this:: complete login type ``example.type.foo``, it might submit something like this::
@ -222,7 +222,7 @@ complete login type ``example.type.foo``, it might submit something like this::
} }
} }
If the home server deems the authentication attempt to be successful but still If the homeserver deems the authentication attempt to be successful but still
requires more stages to be completed, it returns HTTP status 401 along with the requires more stages to be completed, it returns HTTP status 401 along with the
same object as when no authentication was attempted, with the addition of the same object as when no authentication was attempted, with the addition of the
``completed`` key which is an array of stage type the client has completed ``completed`` key which is an array of stage type the client has completed
@ -246,7 +246,7 @@ successfully::
"session": "xxxxxx" "session": "xxxxxx"
} }
If the home server decides the attempt was unsuccessful, it returns an error If the homeserver decides the attempt was unsuccessful, it returns an error
message in the standard format:: message in the standard format::
{ {
@ -258,7 +258,7 @@ Individual stages may require more than one request to complete, in which case
the response will be as if the request was unauthenticated with the addition of the response will be as if the request was unauthenticated with the addition of
any other keys as defined by the login type. any other keys as defined by the login type.
If the client has completed all stages of a flow, the home server performs the If the client has completed all stages of a flow, the homeserver performs the
API call and returns the result as normal. API call and returns the result as normal.
Some authentication types may be completed by means other than through the Some authentication types may be completed by means other than through the
@ -389,16 +389,16 @@ OAuth2-based
``uri``: Authorization Request URI OR service selection URI. Both contain an ``uri``: Authorization Request URI OR service selection URI. Both contain an
encoded ``redirect URI``. encoded ``redirect URI``.
The home server acts as a 'confidential' client for the purposes of OAuth2. If The homeserver acts as a 'confidential' client for the purposes of OAuth2. If
the uri is a ``service selection URI``, it MUST point to a webpage which prompts the uri is a ``service selection URI``, it MUST point to a webpage which prompts
the user to choose which service to authorize with. On selection of a service, the user to choose which service to authorize with. On selection of a service,
this MUST link through to an ``Authorization Request URI``. If there is only one this MUST link through to an ``Authorization Request URI``. If there is only one
service which the home server accepts when logging in, this indirection can be service which the homeserver accepts when logging in, this indirection can be
skipped and the "uri" key can be the ``Authorization Request URI``. skipped and the "uri" key can be the ``Authorization Request URI``.
The client then visits the ``Authorization Request URI``, which then shows the The client then visits the ``Authorization Request URI``, which then shows the
OAuth2 Allow/Deny prompt. Hitting 'Allow' redirects to the ``redirect URI`` with OAuth2 Allow/Deny prompt. Hitting 'Allow' redirects to the ``redirect URI`` with
the auth code. Home servers can choose any path for the ``redirect URI``. Once the auth code. Homeservers can choose any path for the ``redirect URI``. Once
the OAuth flow has completed, the client retries the request with the session the OAuth flow has completed, the client retries the request with the session
only, as above. only, as above.
@ -412,7 +412,7 @@ Email-based (identity server)
Prior to submitting this, the client should authenticate with an identity Prior to submitting this, the client should authenticate with an identity
server. After authenticating, the session information should be submitted to server. After authenticating, the session information should be submitted to
the home server. the homeserver.
To respond to this type, reply with an auth dict as follows:: To respond to this type, reply with an auth dict as follows::
@ -450,12 +450,12 @@ Clients cannot be expected to be able to know how to process every single login
type. If a client does not know how to handle a given login type, it can direct type. If a client does not know how to handle a given login type, it can direct
the user to a web browser with the URL of a fallback page which will allow the the user to a web browser with the URL of a fallback page which will allow the
user to complete that login step out-of-band in their web browser. The URL it user to complete that login step out-of-band in their web browser. The URL it
should open is the Home Server base URL plus prefix, plus:: should open is the homeserver base URL plus prefix, plus::
/auth/<stage type>/fallback/web?session=<session ID> /auth/<stage type>/fallback/web?session=<session ID>
Where ``stage type`` is the type name of the stage it is attempting and Where ``stage type`` is the type name of the stage it is attempting and
``session id`` is the ID of the session given by the home server. ``session id`` is the ID of the session given by the homeserver.
This MUST return an HTML page which can perform this authentication stage. This This MUST return an HTML page which can perform this authentication stage. This
page must attempt to call the JavaScript function ``window.onAuthDone`` when page must attempt to call the JavaScript function ``window.onAuthDone`` when
@ -494,7 +494,7 @@ Request::
This API endpoint uses the User-Interactive Authentication API. An access token This API endpoint uses the User-Interactive Authentication API. An access token
should be submitted to this endpoint if the client has an active session. The should be submitted to this endpoint if the client has an active session. The
Home Server may change the flows available depending on whether a valid access homeserver may change the flows available depending on whether a valid access
token is provided. token is provided.
The body of the POST request is a JSON object containing: The body of the POST request is a JSON object containing:
@ -505,7 +505,7 @@ new_password
On success, an empty JSON object is returned. On success, an empty JSON object is returned.
The error code M_NOT_FOUND is returned if the user authenticated with a third The error code M_NOT_FOUND is returned if the user authenticated with a third
party identifier but the Home Server could not find a matching account in its party identifier but the homeserver could not find a matching account in its
database. database.
Adding Account Administrative Contact Information Adding Account Administrative Contact Information
@ -699,7 +699,7 @@ namespaced for each application and reduces the risk of clashes.
Syncing Syncing
~~~~~~~ ~~~~~~~
Clients receive new events by "long-polling" the home server via the events API. Clients receive new events by "long-polling" the homeserver via the events API.
This involves specifying a timeout in the request which will hold This involves specifying a timeout in the request which will hold
open the HTTP connection for a short period of time waiting for new events, open the HTTP connection for a short period of time waiting for new events,
returning early if an event occurs. Only the events API supports long-polling. returning early if an event occurs. Only the events API supports long-polling.
@ -719,7 +719,7 @@ last request left off. Multiple events can be returned per long-poll.
Do we ever support streaming requests? Why not websockets? Do we ever support streaming requests? Why not websockets?
When the client first logs in, they will need to initially synchronise with When the client first logs in, they will need to initially synchronise with
their home server. This is achieved via the initial sync API described below. their homeserver. This is achieved via the initial sync API described below.
This API also returns an ``end`` token which can be used with the event stream. This API also returns an ``end`` token which can be used with the event stream.
{{old_sync_http_api}} {{old_sync_http_api}}
@ -831,7 +831,7 @@ Rooms
Creation Creation
~~~~~~~~ ~~~~~~~~
The home server will create an ``m.room.create`` event when a room is created, The homeserver will create an ``m.room.create`` event when a room is created,
which serves as the root of the event graph for this room. This event also has a which serves as the root of the event graph for this room. This event also has a
``creator`` key which contains the user ID of the room creator. It will also ``creator`` key which contains the user ID of the room creator. It will also
generate several other events in order to manage permissions in this room. This generate several other events in order to manage permissions in this room. This
@ -852,9 +852,9 @@ Room aliases
Servers may host aliases for rooms with human-friendly names. Aliases take the Servers may host aliases for rooms with human-friendly names. Aliases take the
form ``#friendlyname:server.name``. form ``#friendlyname:server.name``.
As room aliases are scoped to a particular home server domain name, it is As room aliases are scoped to a particular homeserver domain name, it is
likely that a home server will reject attempts to maintain aliases on other likely that a homeserver will reject attempts to maintain aliases on other
domain names. This specification does not provide a way for home servers to domain names. This specification does not provide a way for homeservers to
send update requests to other servers. send update requests to other servers.
Rooms store a *partial* list of room aliases via the ``m.room.aliases`` state Rooms store a *partial* list of room aliases via the ``m.room.aliases`` state
@ -867,8 +867,8 @@ appears to have a room alias of ``#alias:example.com``, this SHOULD be checked
to make sure that the room's ID matches the ``room_id`` returned from the to make sure that the room's ID matches the ``room_id`` returned from the
request. request.
Home servers can respond to resolve requests for aliases on other domains than Homeservers can respond to resolve requests for aliases on other domains than
their own by using the federation API to ask other domain name home servers. their own by using the federation API to ask other domain name homeservers.
{{directory_http_api}} {{directory_http_api}}
@ -985,10 +985,10 @@ values. This change is conveyed using two separate mechanisms:
values of the ``displayname`` and ``avatar_url`` keys, in addition to the values of the ``displayname`` and ``avatar_url`` keys, in addition to the
required ``presence`` key containing the current presence state of the user. required ``presence`` key containing the current presence state of the user.
Both of these should be done automatically by the home server when a user Both of these should be done automatically by the homeserver when a user
successfully changes their display name or avatar URL fields. successfully changes their display name or avatar URL fields.
Additionally, when home servers emit room membership events for their own Additionally, when homeservers emit room membership events for their own
users, they should include the display name and avatar URL fields in these users, they should include the display name and avatar URL fields in these
events so that clients already have these details to hand, and do not have to events so that clients already have these details to hand, and do not have to
perform extra round trips to query it. perform extra round trips to query it.
@ -998,7 +998,7 @@ Security
Rate limiting Rate limiting
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
Home servers SHOULD implement rate limiting to reduce the risk of being Homeservers SHOULD implement rate limiting to reduce the risk of being
overloaded. If a request is refused due to rate limiting, it should return a overloaded. If a request is refused due to rate limiting, it should return a
standard error response of the form:: standard error response of the form::

4
specification/intro.rst
Unescape Escape View File

@ -140,7 +140,7 @@ a long-lived GET request.
| V | V | V | V
+------------------+ +------------------+ +------------------+ +------------------+
| |---------( HTTPS )--------->| | | |---------( HTTPS )--------->| |
| Home Server | | Home Server | | homeserver | | homeserver |
| |<--------( HTTPS )----------| | | |<--------( HTTPS )----------| |
+------------------+ Server-Server API +------------------+ +------------------+ Server-Server API +------------------+
History Synchronisation History Synchronisation
@ -227,7 +227,7 @@ They are case-sensitive. The following conceptual diagram shows an
| | | |
V | V |
+------------------+ +------------------+ +------------------+ +------------------+
| Home Server | | Home Server | | homeserver | | homeserver |
| matrix.org | | domain.com | | matrix.org | | domain.com |
+------------------+ +------------------+ +------------------+ +------------------+
| ^ | ^

4
specification/modules/presence.rst
Unescape Escape View File

@ -61,7 +61,7 @@ recommended.
Server behaviour Server behaviour
---------------- ----------------
Each user's home server stores a "presence list" per user. Once a user accepts Each user's homeserver stores a "presence list" per user. Once a user accepts
a presence list, both user's HSes must track the subscription. a presence list, both user's HSes must track the subscription.
Propagating profile information Propagating profile information
@ -73,7 +73,7 @@ automatic propagation event to occur, informing likely-interested parties of the
new values. One of these change mechanisms SHOULD be via ``m.presence`` events. new values. One of these change mechanisms SHOULD be via ``m.presence`` events.
These events should set ``displayname`` and ``avatar_url`` to the new values These events should set ``displayname`` and ``avatar_url`` to the new values
along with the presence-specific keys. This SHOULD be done automatically by the along with the presence-specific keys. This SHOULD be done automatically by the
home server when a user successfully changes their display name or avatar URL. homeserver when a user successfully changes their display name or avatar URL.
.. admonition:: Rationale .. admonition:: Rationale

2
specification/modules/push.rst
Unescape Escape View File

@ -11,7 +11,7 @@ Push Notifications
| | | | | | | |
+-------------------+ | +----------------+ | | +---------------+ | +-------------------+ | +----------------+ | | +---------------+ |
| | | | | | | | | | | | | | | | | | | |
| Matrix Home Server+-----> Push Gateway +------> Push Provider | | | Matrix homeserver+-----> Push Gateway +------> Push Provider | |
| | | | | | | | | | | | | | | | | | | |
+-^-----------------+ | +----------------+ | | +----+----------+ | +-^-----------------+ | +----------------+ | | +----+----------+ |
| | | | | | | | | | | |

50
specification/server_server_api.rst
Unescape Escape View File

@ -1,8 +1,8 @@
Federation API Federation API
============== ==============
Matrix home servers use the Federation APIs (also known as server-server APIs) Matrix homeservers use the Federation APIs (also known as server-server APIs)
to communicate with each other. Home servers use these APIs to push messages to to communicate with each other. Homeservers use these APIs to push messages to
each other in real-time, to request historic messages from each other, and to each other in real-time, to request historic messages from each other, and to
query profile and presence information about users on each other's servers. query profile and presence information about users on each other's servers.
@ -11,10 +11,10 @@ servers. These HTTPS requests are strongly authenticated using public key
signatures at the TLS transport layer and using public key signatures in signatures at the TLS transport layer and using public key signatures in
HTTP Authorization headers at the HTTP layer. HTTP Authorization headers at the HTTP layer.
There are three main kinds of communication that occur between home servers: There are three main kinds of communication that occur between homeservers:
Persisted Data Units (PDUs): Persisted Data Units (PDUs):
These events are broadcast from one home server to any others that have These events are broadcast from one homeserver to any others that have
joined the same room (identified by Room ID). They are persisted in joined the same room (identified by Room ID). They are persisted in
long-term storage and record the history of messages and state for a long-term storage and record the history of messages and state for a
room. room.
@ -25,9 +25,9 @@ Persisted Data Units (PDUs):
deliver them through third-party servers. deliver them through third-party servers.
Ephemeral Data Units (EDUs): Ephemeral Data Units (EDUs):
These events are pushed between pairs of home servers. They are not These events are pushed between pairs of homeservers. They are not
persisted and are not part of the history of a room, nor does the persisted and are not part of the history of a room, nor does the
receiving home server have to reply to them. receiving homeserver have to reply to them.
Queries: Queries:
These are single request/response interactions between a given pair of These are single request/response interactions between a given pair of
@ -38,7 +38,7 @@ Queries:
EDUs and PDUs are further wrapped in an envelope called a Transaction, which is EDUs and PDUs are further wrapped in an envelope called a Transaction, which is
transferred from the origin to the destination home server using an HTTPS PUT transferred from the origin to the destination homeserver using an HTTPS PUT
request. request.
.. contents:: Table of Contents .. contents:: Table of Contents
@ -50,7 +50,7 @@ Server Discovery
Resolving Server Names Resolving Server Names
~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~
Each matrix home server is identified by a server name consisting of a DNS name Each matrix homeserver is identified by a server name consisting of a DNS name
and an optional TLS port. and an optional TLS port.
.. code:: .. code::
@ -67,7 +67,7 @@ is absent then the server is discovered by looking up a ``_matrix._tcp`` SRV
record for the DNS name. If this record does not exist then the server is record for the DNS name. If this record does not exist then the server is
discovered by looking up an AAAA or A record on the DNS name and taking the discovered by looking up an AAAA or A record on the DNS name and taking the
default fallback port number of 8448. default fallback port number of 8448.
Home servers may use SRV records to load balance requests between multiple TLS Homeservers may use SRV records to load balance requests between multiple TLS
endpoints or to failover to another endpoint if an endpoint fails. endpoints or to failover to another endpoint if an endpoint fails.
Retrieving Server Keys Retrieving Server Keys
@ -76,8 +76,8 @@ Retrieving Server Keys
Version 2 Version 2
+++++++++ +++++++++
Each home server publishes its public keys under ``/_matrix/key/v2/server/``. Each homeserver publishes its public keys under ``/_matrix/key/v2/server/``.
Home servers query for keys by either getting ``/_matrix/key/v2/server/`` Homeservers query for keys by either getting ``/_matrix/key/v2/server/``
directly or by querying an intermediate notary server using a directly or by querying an intermediate notary server using a
``/_matrix/key/v2/query`` API. Intermediate notary servers query the ``/_matrix/key/v2/query`` API. Intermediate notary servers query the
``/_matrix/key/v2/server/`` API on behalf of another server and sign the ``/_matrix/key/v2/server/`` API on behalf of another server and sign the
@ -95,7 +95,7 @@ server by querying other servers.
Publishing Keys Publishing Keys
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
Home servers publish the allowed TLS fingerprints and signing keys in a JSON Homeservers publish the allowed TLS fingerprints and signing keys in a JSON
object at ``/_matrix/key/v2/server/{key_id}``. The response contains a list of object at ``/_matrix/key/v2/server/{key_id}``. The response contains a list of
``verify_keys`` that are valid for signing federation requests made by the ``verify_keys`` that are valid for signing federation requests made by the
server and for signing events. It contains a list of ``old_verify_keys`` server and for signing events. It contains a list of ``old_verify_keys``
@ -114,7 +114,7 @@ certificate currently in use by the server. These fingerprints are valid until
the millisecond POSIX timestamp in ``valid_until_ts``. the millisecond POSIX timestamp in ``valid_until_ts``.
The ``verify_keys`` can be used to sign requests and events made by the server The ``verify_keys`` can be used to sign requests and events made by the server
until the millisecond POSIX timestamp in ``valid_until_ts``. If a Home Server until the millisecond POSIX timestamp in ``valid_until_ts``. If a homeserver
receives an event with a ``origin_server_ts`` after the ``valid_until_ts`` then receives an event with a ``origin_server_ts`` after the ``valid_until_ts`` then
it should request that ``key_id`` for the originating server to check whether it should request that ``key_id`` for the originating server to check whether
the key has expired. the key has expired.
@ -136,8 +136,8 @@ events sent by that server can still be checked.
==================== =================== ====================================== ==================== =================== ======================================
Key Type Description Key Type Description
==================== =================== ====================================== ==================== =================== ======================================
``server_name`` String DNS name of the home server. ``server_name`` String DNS name of the homeserver.
``verify_keys`` Object Public keys of the home server for ``verify_keys`` Object Public keys of the homeserver for
verifying digital signatures. verifying digital signatures.
``old_verify_keys`` Object The public keys that the server used ``old_verify_keys`` Object The public keys that the server used
to use and when it stopped using them. to use and when it stopped using them.
@ -238,14 +238,14 @@ Version 1
Version 1 of key distribution is obsolete Version 1 of key distribution is obsolete
Home servers publish their TLS certificates and signing keys in a JSON object Homeservers publish their TLS certificates and signing keys in a JSON object
at ``/_matrix/key/v1``. at ``/_matrix/key/v1``.
==================== =================== ====================================== ==================== =================== ======================================
Key Type Description Key Type Description
==================== =================== ====================================== ==================== =================== ======================================
``server_name`` String DNS name of the home server. ``server_name`` String DNS name of the homeserver.
``verify_keys`` Object Public keys of the home server for ``verify_keys`` Object Public keys of the homeserver for
verifying digital signatures. verifying digital signatures.
``signatures`` Object Digital signatures for this object ``signatures`` Object Digital signatures for this object
signed using the ``verify_keys``. signed using the ``verify_keys``.
@ -278,9 +278,9 @@ Transactions
.. WARNING:: .. WARNING::
This section may be misleading or inaccurate. This section may be misleading or inaccurate.
The transfer of EDUs and PDUs between home servers is performed by an exchange The transfer of EDUs and PDUs between homeservers is performed by an exchange
of Transaction messages, which are encoded as JSON objects, passed over an HTTP of Transaction messages, which are encoded as JSON objects, passed over an HTTP
PUT request. A Transaction is meaningful only to the pair of home servers that PUT request. A Transaction is meaningful only to the pair of homeservers that
exchanged it; they are not globally-meaningful. exchanged it; they are not globally-meaningful.
Each transaction has: Each transaction has:
@ -445,7 +445,7 @@ EDUs
EDUs, by comparison to PDUs, do not have an ID, a room ID, or a list of EDUs, by comparison to PDUs, do not have an ID, a room ID, or a list of
"previous" IDs. The only mandatory fields for these are the type, origin and "previous" IDs. The only mandatory fields for these are the type, origin and
destination home server names, and the actual nested content. destination homeserver names, and the actual nested content.
======================== ============ ========================================= ======================== ============ =========================================
Key Type Description Key Type Description
@ -531,7 +531,7 @@ To make a query::
Query args: as specified by the individual query types Query args: as specified by the individual query types
Response: JSON encoding of a response object Response: JSON encoding of a response object
Performs a single query request on the receiving home server. The Query Type Performs a single query request on the receiving homeserver. The Query Type
part of the path specifies the kind of query being made, and its query part of the path specifies the kind of query being made, and its query
arguments have a meaning specific to that kind of query. The response is a arguments have a meaning specific to that kind of query. The response is a
JSON-encoded object whose meaning also depends on the kind of query. JSON-encoded object whose meaning also depends on the kind of query.
@ -791,9 +791,9 @@ because HTTP services like Matrix are often deployed behind load balancers that
handle the TLS and these load balancers make it difficult to check TLS client handle the TLS and these load balancers make it difficult to check TLS client
certificates. certificates.
A home server may provide a TLS client certificate and the receiving home server A homeserver may provide a TLS client certificate and the receiving homeserver
may check that the client certificate matches the certificate of the origin may check that the client certificate matches the certificate of the origin
home server. homeserver.
Server-Server Authorization Server-Server Authorization
--------------------------- ---------------------------
@ -905,7 +905,7 @@ Querying profile information::
If the query contains the optional ``field`` key, it should give the name of a If the query contains the optional ``field`` key, it should give the name of a
result field. If such is present, then the result should contain only a field result field. If such is present, then the result should contain only a field
of that name, with no others present. If not, the result should contain as much of that name, with no others present. If not, the result should contain as much
of the user's profile as the home server has available and can make public. of the user's profile as the homeserver has available and can make public.
Directory Directory
--------- ---------

8
supporting-docs/examples/application-services.rst
Unescape Escape View File

@ -6,15 +6,15 @@ This file contains examples of some application service
IRC Bridge IRC Bridge
---------- ----------
Pre-conditions: Pre-conditions:
- Server admin stores the AS token "T_a" on the home server. - Server admin stores the AS token "T_a" on the homeserver.
- Home server has a token "T_h". - Homeserver has a token "T_h".
- Home server has the domain "hsdomain.com" - Homeserver has the domain "hsdomain.com"
1. Application service registration 1. Application service registration
:: ::
AS -> HS: Registers itself with the home server AS -> HS: Registers itself with the homeserver
POST /register POST /register
{ {
url: "https://someapp.com/matrix", url: "https://someapp.com/matrix",

16
supporting-docs/guides/2015-08-10-client-server.rst
Unescape Escape View File

@ -19,11 +19,11 @@ How to use the client-server API
The git version of this document is {% project_version %} The git version of this document is {% project_version %}
This guide focuses on how the client-server APIs *provided by the reference This guide focuses on how the client-server APIs *provided by the reference
home server* can be used. Since this is specific to a home server homeserver* can be used. Since this is specific to a homeserver
implementation, there may be variations in relation to registering/logging in implementation, there may be variations in relation to registering/logging in
which are not covered in extensive detail in this guide. which are not covered in extensive detail in this guide.
If you haven't already, get a home server up and running on If you haven't already, get a homeserver up and running on
``http://localhost:8008``. ``http://localhost:8008``.
@ -56,8 +56,8 @@ if you forget the ``access_token``.
Implementation note: The matrix specification does not enforce how users Implementation note: The matrix specification does not enforce how users
register with a server. It just specifies the URL path and absolute minimum register with a server. It just specifies the URL path and absolute minimum
keys. The reference home server uses a username/password to authenticate user, keys. The reference homeserver uses a username/password to authenticate user,
but other home servers may use different methods. This is why you need to but other homeservers may use different methods. This is why you need to
specify the ``type`` of method. specify the ``type`` of method.
Login Login
@ -82,13 +82,13 @@ The aim when logging in is to get an access token for your existing user ID::
"user_id": "@example:localhost" "user_id": "@example:localhost"
} }
Implementation note: Different home servers may implement different methods for Implementation note: Different homeservers may implement different methods for
logging in to an existing account. In order to check that you know how to login logging in to an existing account. In order to check that you know how to login
to this home server, you must perform a ``GET`` first and make sure you to this homeserver, you must perform a ``GET`` first and make sure you
recognise the login type. If you do not know how to login, you can recognise the login type. If you do not know how to login, you can
``GET /login/fallback`` which will return a basic webpage which you can use to ``GET /login/fallback`` which will return a basic webpage which you can use to
login. The reference home server implementation support username/password login, login. The reference homeserver implementation support username/password login,
but other home servers may support different login methods (e.g. OAuth2). but other homeservers may support different login methods (e.g. OAuth2).
Communicating Communicating

18
supporting-docs/guides/2015-08-21-application_services.md
Unescape Escape View File

@ -6,7 +6,7 @@ categories: guides
# Application services # Application services
Application services are distinct modules which which sit alongside a home server providing arbitrary extensible functionality decoupled from the home server implementation. Just like the rest of Matrix, they communicate via HTTP using JSON. Application services function in a very similar way to traditional clients, but they are given much more power than a normal client. They can reserve entire namespaces of room aliases and user IDs for their own purposes. They can silently monitor events in rooms, or any events directed at any user ID. This power allows application services to have extremely useful abilities which overall enhance the end user experience. Application services are distinct modules which which sit alongside a homeserver providing arbitrary extensible functionality decoupled from the homeserver implementation. Just like the rest of Matrix, they communicate via HTTP using JSON. Application services function in a very similar way to traditional clients, but they are given much more power than a normal client. They can reserve entire namespaces of room aliases and user IDs for their own purposes. They can silently monitor events in rooms, or any events directed at any user ID. This power allows application services to have extremely useful abilities which overall enhance the end user experience.
| |
@ -47,17 +47,17 @@ At present, the IRC application service is in beta, and is being run on #matrix
| |
# What Application services can do for you # What Application services can do for you
Application services have enormous potential for creating new and exciting ways to transform and enhance the core Matrix protocol. For example, you could aggregate information from multiple rooms into a summary room, or create throwaway virtual user accounts to proxy messages for a fixed user ID on-the-fly. As you may expect, all of this power assumes a high degree of trust between application services and home servers. Only home server admins can allow an application service to link up with their home server, and the application service is in no way federated to other home servers. You can think of application services as additional logic on the home server itself, without messing around with the book-keeping that home servers have to do. This makes adding useful functionality very easy. Application services have enormous potential for creating new and exciting ways to transform and enhance the core Matrix protocol. For example, you could aggregate information from multiple rooms into a summary room, or create throwaway virtual user accounts to proxy messages for a fixed user ID on-the-fly. As you may expect, all of this power assumes a high degree of trust between application services and homeservers. Only homeserver admins can allow an application service to link up with their homeserver, and the application service is in no way federated to other homeservers. You can think of application services as additional logic on the homeserver itself, without messing around with the book-keeping that homeservers have to do. This makes adding useful functionality very easy.
| |
### Example ### Example
The application service (AS) API itself uses webhooks to communicate from the home server to the AS: The application service (AS) API itself uses webhooks to communicate from the homeserver to the AS:
- Room Alias Query API : The home server hits a URL on your application server to see if a room alias exists. - Room Alias Query API : The homeserver hits a URL on your application server to see if a room alias exists.
- User Query API : The home server hits a URL on your application server to see if a user ID exists. - User Query API : The homeserver hits a URL on your application server to see if a user ID exists.
- Push API : The home server hits a URL on your application server to notify you of new events for your users and rooms. - Push API : The homeserver hits a URL on your application server to notify you of new events for your users and rooms.
A very basic application service may want to log all messages in rooms which have an alias starting with "#logged_" (side note: logging won't work if these rooms are using end-to-end encryption). A very basic application service may want to log all messages in rooms which have an alias starting with "#logged_" (side note: logging won't work if these rooms are using end-to-end encryption).
@ -85,7 +85,7 @@ Set your new application service running on port 5000 with:
python app_service.py python app_service.py
The home server needs to know that the application service exists before it will send requests to it. This is done via a registration YAML file which is specified in Synapse's main config file e.g. <code>homeserver.yaml</code>. The server admin needs to add the application service registration configuration file as an entry to this file. The homeserver needs to know that the application service exists before it will send requests to it. This is done via a registration YAML file which is specified in Synapse's main config file e.g. <code>homeserver.yaml</code>. The server admin needs to add the application service registration configuration file as an entry to this file.
# homeserver.yaml # homeserver.yaml
app_service_config_files: app_service_config_files:
@ -115,7 +115,7 @@ NB: Note the "-" at the start; this indicates a list element. The registration f
- exclusive: false - exclusive: false
regex: "#logged_.*" regex: "#logged_.*"
**You will need to restart the home server after editing the config file before it will take effect.** **You will need to restart the homeserver after editing the config file before it will take effect.**
| |
@ -138,6 +138,6 @@ This makes the application service lazily create a room with the requested alias
| |
Application services are powerful components which extend the functionality of home servers, but they are limited. They can only ever function in a "passive" way. For example, you cannot implement an application service which censors swear words in rooms, because there is no way to prevent the event from being sent. Aside from the fact that censoring will not work when using end-to-end encryption, all federated home servers would also need to reject the event in order to stop developing an inconsistent event graph. To "actively" monitor events, another component called a "Policy Server" is required, which is beyond the scope of this post.  Also, Application Services can result in a performance bottleneck, as all events on the homeserver must be ordered and sent to the registered application services.  If you are bridging huge amounts of traffic, you may be better off having your bridge directly talk the Server-Server federation API rather than the simpler Application Service API. Application services are powerful components which extend the functionality of homeservers, but they are limited. They can only ever function in a "passive" way. For example, you cannot implement an application service which censors swear words in rooms, because there is no way to prevent the event from being sent. Aside from the fact that censoring will not work when using end-to-end encryption, all federated homeservers would also need to reject the event in order to stop developing an inconsistent event graph. To "actively" monitor events, another component called a "Policy Server" is required, which is beyond the scope of this post.  Also, Application Services can result in a performance bottleneck, as all events on the homeserver must be ordered and sent to the registered application services.  If you are bridging huge amounts of traffic, you may be better off having your bridge directly talk the Server-Server federation API rather than the simpler Application Service API.
I hope this demonstrates how easy it is to create an application service, along with a few ideas of the kinds of things you can do with them. Obvious uses include build protocol bridges, search engines, invisible bots, etc. For more information on the AS HTTP API, check out the new <a href="http://matrix.org/docs/spec/#application-service-api">Application Service API</a> section in the spec, or the raw drafts and spec in <a href="https://github.com/matrix-org/matrix-doc/" target="_blank">https://github.com/matrix-org/matrix-doc/</a>. I hope this demonstrates how easy it is to create an application service, along with a few ideas of the kinds of things you can do with them. Obvious uses include build protocol bridges, search engines, invisible bots, etc. For more information on the AS HTTP API, check out the new <a href="http://matrix.org/docs/spec/#application-service-api">Application Service API</a> section in the spec, or the raw drafts and spec in <a href="https://github.com/matrix-org/matrix-doc/" target="_blank">https://github.com/matrix-org/matrix-doc/</a>.

16
supporting-docs/howtos/client-server.rst
Unescape Escape View File

@ -11,11 +11,11 @@ How to use the client-server API
The git version of this document is ``{{git_version}}`` The git version of this document is ``{{git_version}}``
This guide focuses on how the client-server APIs *provided by the reference This guide focuses on how the client-server APIs *provided by the reference
home server* can be used. Since this is specific to a home server homeserver* can be used. Since this is specific to a homeserver
implementation, there may be variations in relation to registering/logging in implementation, there may be variations in relation to registering/logging in
which are not covered in extensive detail in this guide. which are not covered in extensive detail in this guide.
If you haven't already, get a home server up and running on If you haven't already, get a homeserver up and running on
``http://localhost:8008``. ``http://localhost:8008``.
@ -48,8 +48,8 @@ if you forget the ``access_token``.
Implementation note: The matrix specification does not enforce how users Implementation note: The matrix specification does not enforce how users
register with a server. It just specifies the URL path and absolute minimum register with a server. It just specifies the URL path and absolute minimum
keys. The reference home server uses a username/password to authenticate user, keys. The reference homeserver uses a username/password to authenticate user,
but other home servers may use different methods. This is why you need to but other homeservers may use different methods. This is why you need to
specify the ``type`` of method. specify the ``type`` of method.
Login Login
@ -74,13 +74,13 @@ The aim when logging in is to get an access token for your existing user ID::
"user_id": "@example:localhost" "user_id": "@example:localhost"
} }
Implementation note: Different home servers may implement different methods for Implementation note: Different homeservers may implement different methods for
logging in to an existing account. In order to check that you know how to login logging in to an existing account. In order to check that you know how to login
to this home server, you must perform a ``GET`` first and make sure you to this homeserver, you must perform a ``GET`` first and make sure you
recognise the login type. If you do not know how to login, you can recognise the login type. If you do not know how to login, you can
``GET /login/fallback`` which will return a basic webpage which you can use to ``GET /login/fallback`` which will return a basic webpage which you can use to
login. The reference home server implementation support username/password login, login. The reference homeserver implementation support username/password login,
but other home servers may support different login methods (e.g. OAuth2). but other homeservers may support different login methods (e.g. OAuth2).
Communicating Communicating

2
supporting-docs/howtos/jsfiddles/create_room_send_msg/demo.html
Unescape Escape View File

@ -1,5 +1,5 @@
<div> <div>
<p>This room creation / message sending demo requires a home server to be running on http://localhost:8008</p> <p>This room creation / message sending demo requires a homeserver to be running on http://localhost:8008</p>
</div> </div>
<form class="loginForm"> <form class="loginForm">
<input type="text" id="userLogin" placeholder="Username"></input> <input type="text" id="userLogin" placeholder="Username"></input>

2
supporting-docs/howtos/jsfiddles/create_room_send_msg/demo.js
Unescape Escape View File

@ -19,7 +19,7 @@ $('.login').live('click', function() {
showLoggedIn(data); showLoggedIn(data);
}, },
error: function(err) { error: function(err) {
var errMsg = "To try this, you need a home server running!"; var errMsg = "To try this, you need a homeserver running!";
var errJson = $.parseJSON(err.responseText); var errJson = $.parseJSON(err.responseText);
if (errJson) { if (errJson) {
errMsg = JSON.stringify(errJson); errMsg = JSON.stringify(errJson);

2
supporting-docs/howtos/jsfiddles/event_stream/demo.html
Unescape Escape View File

@ -1,5 +1,5 @@
<div> <div>
<p>This event stream demo requires a home server to be running on http://localhost:8008</p> <p>This event stream demo requires a homeserver to be running on http://localhost:8008</p>
</div> </div>
<form class="loginForm"> <form class="loginForm">
<input type="text" id="userLogin" placeholder="Username"></input> <input type="text" id="userLogin" placeholder="Username"></input>

2
supporting-docs/howtos/jsfiddles/event_stream/demo.js
Unescape Escape View File

@ -58,7 +58,7 @@ $('.login').live('click', function() {
showLoggedIn(data); showLoggedIn(data);
}, },
error: function(err) { error: function(err) {
var errMsg = "To try this, you need a home server running!"; var errMsg = "To try this, you need a homeserver running!";
var errJson = $.parseJSON(err.responseText); var errJson = $.parseJSON(err.responseText);
if (errJson) { if (errJson) {
errMsg = JSON.stringify(errJson); errMsg = JSON.stringify(errJson);

2
supporting-docs/howtos/jsfiddles/example_app/demo.html
Unescape Escape View File

@ -1,5 +1,5 @@
<div class="signUp"> <div class="signUp">
<p>Matrix example application: Requires a local home server running at http://localhost:8008</p> <p>Matrix example application: Requires a local homeserver running at http://localhost:8008</p>
<form class="registrationForm"> <form class="registrationForm">
<p>No account? Register:</p> <p>No account? Register:</p>
<input type="text" id="userReg" placeholder="Username"></input> <input type="text" id="userReg" placeholder="Username"></input>

4
supporting-docs/howtos/jsfiddles/example_app/demo.js
Unescape Escape View File

@ -98,7 +98,7 @@ $('.login').live('click', function() {
onLoggedIn(data); onLoggedIn(data);
}, },
error: function(err) { error: function(err) {
alert("Unable to login: is the home server running?"); alert("Unable to login: is the homeserver running?");
} }
}); });
}); });
@ -116,7 +116,7 @@ $('.register').live('click', function() {
onLoggedIn(data); onLoggedIn(data);
}, },
error: function(err) { error: function(err) {
var msg = "Is the home server running?"; var msg = "Is the homeserver running?";
var errJson = $.parseJSON(err.responseText); var errJson = $.parseJSON(err.responseText);
if (errJson !== null) { if (errJson !== null) {
msg = errJson.error; msg = errJson.error;

2
supporting-docs/howtos/jsfiddles/register_login/demo.html
Unescape Escape View File

@ -1,5 +1,5 @@
<div> <div>
<p>This registration/login demo requires a home server to be running on http://localhost:8008</p> <p>This registration/login demo requires a homeserver to be running on http://localhost:8008</p>
</div> </div>
<form class="registrationForm"> <form class="registrationForm">
<input type="text" id="user" placeholder="Username"></input> <input type="text" id="user" placeholder="Username"></input>

4
supporting-docs/howtos/jsfiddles/register_login/demo.js
Unescape Escape View File

@ -20,7 +20,7 @@ $('.register').live('click', function() {
showLoggedIn(data); showLoggedIn(data);
}, },
error: function(err) { error: function(err) {
var errMsg = "To try this, you need a home server running!"; var errMsg = "To try this, you need a homeserver running!";
var errJson = $.parseJSON(err.responseText); var errJson = $.parseJSON(err.responseText);
if (errJson) { if (errJson) {
errMsg = JSON.stringify(errJson); errMsg = JSON.stringify(errJson);
@ -41,7 +41,7 @@ var login = function(user, password) {
showLoggedIn(data); showLoggedIn(data);
}, },
error: function(err) { error: function(err) {
var errMsg = "To try this, you need a home server running!"; var errMsg = "To try this, you need a homeserver running!";
var errJson = $.parseJSON(err.responseText); var errJson = $.parseJSON(err.responseText);
if (errJson) { if (errJson) {
errMsg = JSON.stringify(errJson); errMsg = JSON.stringify(errJson);

2
supporting-docs/howtos/jsfiddles/room_memberships/demo.html
Unescape Escape View File

@ -1,5 +1,5 @@
<div> <div>
<p>This room membership demo requires a home server to be running on http://localhost:8008</p> <p>This room membership demo requires a homeserver to be running on http://localhost:8008</p>
</div> </div>
<form class="loginForm"> <form class="loginForm">
<input type="text" id="userLogin" placeholder="Username"></input> <input type="text" id="userLogin" placeholder="Username"></input>

2
supporting-docs/howtos/jsfiddles/room_memberships/demo.js
Unescape Escape View File

@ -28,7 +28,7 @@ $('.login').live('click', function() {
showLoggedIn(data); showLoggedIn(data);
}, },
error: function(err) { error: function(err) {
var errMsg = "To try this, you need a home server running!"; var errMsg = "To try this, you need a homeserver running!";
var errJson = $.parseJSON(err.responseText); var errJson = $.parseJSON(err.responseText);
if (errJson) { if (errJson) {
errMsg = JSON.stringify(errJson); errMsg = JSON.stringify(errJson);

Write Preview
Loading…
Cancel
Save