Add room query API. Remove linking API.
Also add section on ID conventions which need thinking about.
This commit is contained in:
Kegsay
parent
f33b722e4b
commit
1d45dc08ca
1 changed files with 86 additions and 95 deletions
|
|
@ -13,7 +13,8 @@ Registration API ``[Draft]``
|
|||
.. NOTE::
|
||||
- Do we really have to use regex for this? Can't we do this a nicer way?
|
||||
|
||||
This API registers the application service with its host homeserver to offer its services.
|
||||
This API registers the application service with its host homeserver to offer its
|
||||
services.
|
||||
|
||||
Inputs:
|
||||
- Credentials (e.g. some kind of string token)
|
||||
|
|
@ -21,7 +22,8 @@ Inputs:
|
|||
- Namespace[room aliases]
|
||||
- URL base to receive inbound comms
|
||||
Output:
|
||||
- The credentials the HS will use to query the AS with in return. (e.g. some kind of string token)
|
||||
- The credentials the HS will use to query the AS with in return. (e.g. some
|
||||
kind of string token)
|
||||
Side effects:
|
||||
- The HS will start delivering events to the URL base specified if this 200s.
|
||||
API called when:
|
||||
|
|
@ -76,7 +78,8 @@ Inputs:
|
|||
Output:
|
||||
- None.
|
||||
Side effects:
|
||||
- The HS will stop delivering events to the URL base specified for this AS if this 200s.
|
||||
- The HS will stop delivering events to the URL base specified for this AS if
|
||||
this 200s.
|
||||
API called when:
|
||||
- The application service wants to stop receiving all events from the HS.
|
||||
|
||||
|
|
@ -97,7 +100,8 @@ This contains application service APIs which are used by the home server.
|
|||
User Query ``[Draft]``
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This API is called by the HS to query the existence of a user on the Application Service's namespace.
|
||||
This API is called by the HS to query the existence of a user on the Application
|
||||
Service's namespace.
|
||||
|
||||
Inputs:
|
||||
- User ID
|
||||
|
|
@ -131,109 +135,84 @@ Notes:
|
|||
}
|
||||
}
|
||||
|
||||
Room Alias Query ``[TODO]``
|
||||
Room Alias Query ``[Draft]``
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
This API is called by the HS to query the existence of a room alias on the Application
|
||||
Service's namespace.
|
||||
This API is called by the HS to query the existence of a room alias on the
|
||||
Application Service's namespace.
|
||||
|
||||
Inputs:
|
||||
- Room alias
|
||||
- HS Credentials
|
||||
Output:
|
||||
- The current state events for the room if any.
|
||||
- The message events for the room if any.
|
||||
Side effects:
|
||||
- A new room will be created with the alias input if this response 200s.
|
||||
API called when:
|
||||
- HS receives an event to join a room alias in the AS's namespace.
|
||||
Notes:
|
||||
- This can be thought of as an ``initialSync`` but for a 3P networked room,
|
||||
which is lazily loaded when a matrix user tries to join the room.
|
||||
|
||||
::
|
||||
|
||||
GET /rooms/$room_alias?access_token=$hs_token
|
||||
|
||||
Returns:
|
||||
200 : Room is recognised.
|
||||
404 : Room not found.
|
||||
401 : Credentials need to be supplied.
|
||||
403 : HS credentials rejected.
|
||||
|
||||
|
||||
200 OK response format
|
||||
|
||||
{
|
||||
events: [
|
||||
{
|
||||
content: {
|
||||
...
|
||||
},
|
||||
user_id: "string",
|
||||
origin_server_ts: integer, // massaged timestamps
|
||||
type: "string"
|
||||
},
|
||||
...
|
||||
],
|
||||
state: [
|
||||
{
|
||||
content: {
|
||||
...
|
||||
},
|
||||
user_id: "string(virtual user id)",
|
||||
origin_server_ts: integer,
|
||||
state_key: "string",
|
||||
type: "string" // e.g. m.room.name
|
||||
},
|
||||
...
|
||||
]
|
||||
}
|
||||
|
||||
Pushing ``[TODO]``
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
This API is called by the HS when the HS wants to push an event (or batch of events) to the AS.
|
||||
This API is called by the HS when the HS wants to push an event (or batch of
|
||||
events) to the AS.
|
||||
|
||||
- Retry semantics
|
||||
- Ordering
|
||||
|
||||
|
||||
|
||||
Client -> Server -> Application Service
|
||||
---------------------------------------
|
||||
This contains home server APIs which are used by the client, to communicate with
|
||||
the application service.
|
||||
|
||||
Linking ``[Draft]``
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
.. NOTE::
|
||||
- How does the application service know that the matrix user really is the virtual
|
||||
user they claim to be? If we force an IS lookup, then this would resolve on its
|
||||
own as anyone who wants to talk to the virtual user will do a lookup before trying
|
||||
the application service...
|
||||
- In other words, what is preventing ``@bob:matrix.org`` masquerading as
|
||||
``@.irc.freenode.alice:matrix.org``?
|
||||
|
||||
Clients may want to link their matrix user ID to their virtual user ID. This
|
||||
API allows the AS to do this, so messages sent from the AS are sent as the client's
|
||||
user ID, instead of the virtual user ID.
|
||||
|
||||
This is not achieved using OAuth2 or similar because the trust relationships are
|
||||
different. The application service already has a huge amount of trust from the
|
||||
home server, unlike a random third-party web app. As a result, the data flow is
|
||||
different because the third-party (the application service) is trusted by the
|
||||
authorisation entity (the home server). Furthermore, it is desirable to not have
|
||||
the clients communicate directly with the application service in order to
|
||||
decrease the complexity of AS design.
|
||||
|
||||
To grant permission for an application service to masquerade as a user:
|
||||
|
||||
Inputs:
|
||||
- Credentials of user (e.g. ``access_token``)
|
||||
- The user ID within an application service's namespace to claim.
|
||||
- Restrictions if any (e.g. only for rooms X,Y,Z. Only for 10 hours. etc)
|
||||
Output:
|
||||
- None.
|
||||
Side effects:
|
||||
- The home server will generate an ``access_token`` and push it to the
|
||||
application service along with both user IDs if this response 200s.
|
||||
Notes:
|
||||
- Repeated calls to this API should invalidate any existing token for this
|
||||
user ID / application service combo and provision a new token which is then
|
||||
pushed.
|
||||
- The generated access token MUST honour the restrictions laid out by the
|
||||
client.
|
||||
|
||||
::
|
||||
|
||||
PUT /appservices/$virtual_user_id?access_token=$token
|
||||
|
||||
Request format
|
||||
{
|
||||
restrictions: {
|
||||
expires_in: 3600,
|
||||
rooms: [
|
||||
"!fl3rwfehw:matrix.org",
|
||||
"!fwet2yugs:matrix.org"
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
To revoke permission for an application service to masquerade as a user:
|
||||
|
||||
Inputs:
|
||||
- Credentials of user (e.g. ``access_token``)
|
||||
- The user ID within an application service's namespace to revoke. If blank,
|
||||
revokes all virtual user IDs linked to this matrix user ID.
|
||||
Output:
|
||||
- None.
|
||||
Side effects:
|
||||
- The home server invalidate all access tokens for this user ID / AS combo
|
||||
and push this invalidation to the application service if this response 200s.
|
||||
|
||||
::
|
||||
|
||||
DELETE /appservices/$virtual_user_id?access_token=$token
|
||||
|
||||
|
||||
Client-Server v2 API Extensions
|
||||
-------------------------------
|
||||
|
||||
Identity assertion
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
The client-server API infers the user ID from the ``access_token`` provided in every
|
||||
request. It would be an annoying amount of book-keeping to maintain tokens for every
|
||||
virtual user. It would be preferable if the application service could use the CS API
|
||||
with its own ``as_token`` instead, and specify the virtual user they wish to be
|
||||
acting on behalf of. For real users, this would require additional permissions (see
|
||||
"C-AS Linking").
|
||||
The client-server API infers the user ID from the ``access_token`` provided in
|
||||
every request. It would be an annoying amount of book-keeping to maintain tokens
|
||||
for every virtual user. It would be preferable if the application service could
|
||||
use the CS API with its own ``as_token`` instead, and specify the virtual user
|
||||
they wish to be acting on behalf of. For real users, this would require
|
||||
additional permissions (see "C-AS Linking").
|
||||
|
||||
Inputs:
|
||||
- Application service token (``access_token``)
|
||||
|
|
@ -243,9 +222,9 @@ Inputs:
|
|||
- OAuth2 token of real user (which may end up being an access token)
|
||||
Notes:
|
||||
- This will apply on all aspects of the CS API, except for Account Management.
|
||||
- The ``as_token`` is inserted into ``access_token`` which is usually where the client
|
||||
token is. This is done on purpose to allow application services to reuse client
|
||||
SDKs.
|
||||
- The ``as_token`` is inserted into ``access_token`` which is usually where the
|
||||
client token is. This is done on purpose to allow application services to
|
||||
reuse client SDKs.
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -288,3 +267,15 @@ 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
|
||||
create/delete any user in its namespace. This does not require any additional
|
||||
public APIs.
|
||||
|
||||
|
||||
ID conventions
|
||||
--------------
|
||||
This concerns the well-defined conventions for mapping 3P network IDs to matrix
|
||||
IDs, which we expect clients to be able to do by themselves.
|
||||
|
||||
- What do user IDs look like? Butchered URIs? Can all 3P network IDs be
|
||||
reasonably expressed as URIs? (e.g. tel, email, irc, xmpp, ...)
|
||||
- What do room aliases look like? Some cases are clear (e.g. IRC) but others
|
||||
are a lot more fiddly (e.g. email? You don't want to share a room with
|
||||
everyone who has ever sent an email to ``bob@gmail.com``)...
|
||||
Loading…
Add table
Add a link
Reference in a new issue